Page cover

Development Setup & Conventions

This guide provides comprehensive instructions for setting up your development environment and understanding the codebase conventions for JuliaOS.

Setting Up Development Environment

Prerequisites

Before you begin, ensure you have the following installed on your system:

Step 1: Clone the Repository

git clone https://github.com/Juliaoscode/JuliaOS.git
cd JuliaOS

Step 2: Install Node.js Dependencies

JuliaOS uses a monorepo structure managed by npm workspaces. Install all dependencies with:

npm install

This will install dependencies for all packages in the /packages directory.

Step 3: Install Julia Dependencies

Activate the Julia environment and install all required packages:

If you encounter any issues with Julia package installation, you can try resolving them with:

Step 4: Install Python Dependencies (Optional)

If you plan to use or develop the Python wrapper:

For development with LangChain integration:

Step 5: Configure Environment Variables

Create a .env file in the project root:

Edit the .env file to include necessary configuration:

For development purposes, you can use public RPC endpoints or free tier API keys from providers like Alchemy, Infura, or QuickNode.

Step 6: Start Development Servers

Start the Julia backend server:

In a separate terminal, start the interactive CLI:

Step 7: Verify Installation

To verify that your development environment is set up correctly:

  1. The Julia server should be running without errors on port 8052 (or your configured port)

  2. The CLI should connect to the server and display the main menu

  3. Run a simple test command in the CLI to verify connectivity

Development Workflow

Running Tests

Julia Tests

Or run specific test files:

TypeScript/JavaScript Tests

Or for a specific package:

Python Tests

Building Packages

This will build all packages in the monorepo. To build a specific package:

Development Commands

  • Linting: npm run lint

  • Formatting: npm run format

  • Type Checking: npm run typecheck

  • Watch Mode: npm run dev (for packages that support it)

Codebase Structure

Directory Structure

Component Architecture

JuliaOS follows a modular architecture with clear separation of concerns:

  1. Backend (Julia): High-performance core functionality

    • Agent and swarm implementation

    • Blockchain interaction

    • Storage management

    • Server implementation

  2. Bridge Layer: Communication between backend and clients

    • WebSocket server/client

    • Command handling

    • Event propagation

  3. Client Interfaces:

    • TypeScript/JavaScript framework

    • Python wrapper

    • Interactive CLI

  4. Extensions:

    • Bridge implementations

    • Wallet integrations

    • DEX connectors

Coding Conventions

Julia Conventions

  • Use module-level organization for related functionality

  • Implement comprehensive error handling

  • Write docstrings for all public functions

  • Use type annotations where appropriate

  • Write unit tests for all functionality

Example:

""" function create_agent(name::String, type::String, config::Dict) # Implementation end

Python Conventions

  • Follow PEP 8 style guidelines

  • Use type hints (PEP 484)

  • Document functions with docstrings

  • Use async/await for asynchronous code

  • Write unit tests for all functionality

Example:

Git Workflow

  1. Branching Strategy:

    • main: Stable production code

    • develop: Integration branch for features

    • feature/xxx: Feature branches

    • fix/xxx: Bug fix branches

    • docs/xxx: Documentation updates

  2. Commit Messages: Follow conventional commit standards:

    • feat: add new agent type

    • fix: resolve bridge transfer bug

    • docs: update architecture diagram

    • refactor: improve swarm algorithm performance

    • test: add tests for wallet integration

    • chore: update dependencies

  3. Pull Requests:

    • Create descriptive PR titles

    • Include detailed descriptions

    • Reference related issues

    • Ensure all tests pass

    • Request reviews from appropriate team members

Troubleshooting Common Issues

Julia Package Installation Issues

If you encounter issues with Julia package installation:

Node.js Dependency Issues

If you encounter issues with Node.js dependencies:

Server Connection Issues

If the CLI cannot connect to the Julia server:

  1. Ensure the server is running on the correct port

  2. Check for firewall or network issues

  3. Verify the .env configuration

  4. Check server logs for errors

Python Wrapper Issues

If you encounter issues with the Python wrapper:

Next Steps

Now that you have set up your development environment, you can:

  • Explore the CLI Guide to learn how to use the CLI

  • Check out the Framework Modules to understand the core components

  • Read the Extending Guide to learn how to extend JuliaOS

  • Review the Best Practices for development guidelines