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:
Git: For version control (Download)
Node.js: v16+ (Download)
npm: v7+ (Usually included with Node.js)
Julia: v1.8+ (Download)
Python: v3.8+ (for Python wrapper) (Download)
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:
julia -e 'using Pkg; Pkg.activate("julia"); Pkg.instantiate()'
If you encounter any issues with Julia package installation, you can try resolving them with:
julia -e 'using Pkg; Pkg.activate("julia"); Pkg.resolve(); Pkg.instantiate()'
Step 4: Install Python Dependencies (Optional)
If you plan to use or develop the Python wrapper:
pip install -e ./packages/python-wrapper
For development with LangChain integration:
pip install -e "./packages/python-wrapper[langchain]"
Step 5: Configure Environment Variables
Create a .env
file in the project root:
cp .env.example .env # If .env.example exists
# Otherwise, create a new .env file
Edit the .env
file to include necessary configuration:
# Ethereum and EVM chains
ETHEREUM_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY
ETHEREUM_SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY
POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY
ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_API_KEY
OPTIMISM_RPC_URL=https://opt-mainnet.g.alchemy.com/v2/YOUR_API_KEY
BASE_RPC_URL=https://mainnet.base.org
AVALANCHE_RPC_URL=https://api.avax.network/ext/bc/C/rpc
BSC_RPC_URL=https://bsc-dataseed.binance.org
FANTOM_RPC_URL=https://rpc.ftm.tools
# Solana
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
# API Keys (if needed)
ALCHEMY_API_KEY=YOUR_ALCHEMY_API_KEY
INFURA_API_KEY=YOUR_INFURA_API_KEY
# Server Configuration
JULIAOS_SERVER_PORT=8052
JULIAOS_SERVER_HOST=localhost
# Storage Configuration
STORAGE_PATH=~/.juliaos
# LLM Configuration (if using)
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
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:
cd julia
julia julia_server.jl
In a separate terminal, start the interactive CLI:
cd /path/to/JuliaOS
node packages/cli/interactive.cjs
Step 7: Verify Installation
To verify that your development environment is set up correctly:
The Julia server should be running without errors on port 8052 (or your configured port)
The CLI should connect to the server and display the main menu
Run a simple test command in the CLI to verify connectivity
Development Workflow
Running Tests
Julia Tests
cd julia
julia -e 'using Pkg; Pkg.activate("."); Pkg.test()'
Or run specific test files:
julia -e 'using Pkg; Pkg.activate("."); include("test/runtests.jl")'
TypeScript/JavaScript Tests
npm test
Or for a specific package:
cd packages/framework
npm test
Python Tests
cd packages/python-wrapper
python -m pytest
Building Packages
npm run build
This will build all packages in the monorepo. To build a specific package:
cd packages/framework
npm run build
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
JuliaOS/
├── julia/ # Julia backend code
│ ├── src/ # Main Julia source code
│ │ ├── JuliaOS.jl # Main module definition
│ │ ├── Agents.jl # Agent system implementation
│ │ ├── Swarms.jl # Swarm algorithms implementation
│ │ ├── Blockchain.jl # Blockchain interaction
│ │ ├── Bridge.jl # Cross-chain bridge functionality
│ │ ├── DEX.jl # DEX integration
│ │ ├── Storage.jl # Storage functionality
│ │ ├── Wallet.jl # Wallet management
│ │ └── ... # Other modules
│ ├── test/ # Julia tests
│ ├── config/ # Configuration files
│ └── julia_server.jl # Main server entry point
├── packages/ # TypeScript/JavaScript packages
│ ├── cli/ # Interactive CLI
│ ├── framework/ # Core framework for JS/TS applications
│ │ ├── src/ # Source code
│ │ │ ├── agents.ts # Agent management
│ │ │ ├── swarms.ts # Swarm management
│ │ │ ├── bridge.ts # Bridge functionality
│ │ │ ├── dex.ts # DEX integration
│ │ │ ├── wallet.ts # Wallet management
│ │ │ └── ... # Other modules
│ │ └── tests/ # Tests
│ ├── bridges/ # Bridge implementations
│ ├── wallets/ # Wallet integrations
│ └── python-wrapper/ # Python bindings
│ ├── juliaos/ # Python package
│ │ ├── agents/ # Agent functionality
│ │ ├── swarms/ # Swarm functionality
│ │ ├── blockchain/ # Blockchain functionality
│ │ ├── langchain/ # LangChain integration
│ │ └── ... # Other modules
│ └── tests/ # Python tests
├── docs/ # Documentation
│ └── gitbook/ # GitBook documentation
└── .env # Environment variables
Component Architecture
JuliaOS follows a modular architecture with clear separation of concerns:
Backend (Julia): High-performance core functionality
Agent and swarm implementation
Blockchain interaction
Storage management
Server implementation
Bridge Layer: Communication between backend and clients
WebSocket server/client
Command handling
Event propagation
Client Interfaces:
TypeScript/JavaScript framework
Python wrapper
Interactive CLI
Extensions:
Bridge implementations
Wallet integrations
DEX connectors
Coding Conventions
Julia Conventions
Follow the Julia Style Guide
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:
"""
create_agent(name::String, type::String, config::Dict) -> Dict
Create a new agent with the specified name, type, and configuration.
# Arguments
- `name::String`: The name of the agent
- `type::String`: The type of agent (e.g., "trading", "research")
- `config::Dict`: Configuration parameters for the agent
# Returns
- `Dict`: The created agent object with an assigned ID
# Examples
```julia
agent = create_agent("MyAgent", "trading", Dict("risk_level" => "medium"))
""" function create_agent(name::String, type::String, config::Dict) # Implementation end
### TypeScript/JavaScript Conventions
- Use TypeScript for type safety
- Follow ESLint and Prettier configurations
- Use async/await for asynchronous code
- Document functions with JSDoc comments
- Write unit tests for all functionality
- Use named exports for better tree-shaking
Example:
```typescript
/**
* Creates a new agent with the specified parameters
* @param {string} name - The name of the agent
* @param {string} type - The type of agent (e.g., "trading", "research")
* @param {object} config - Configuration parameters for the agent
* @returns {Promise<Agent>} The created agent object
*/
export async function createAgent(
name: string,
type: string,
config: Record<string, any>
): Promise<Agent> {
// Implementation
}
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:
async def create_agent(
name: str,
agent_type: AgentType,
config: Dict[str, Any]
) -> Agent:
"""Create a new agent with the specified parameters.
Args:
name: The name of the agent
agent_type: The type of agent (e.g., TRADING, RESEARCH)
config: Configuration parameters for the agent
Returns:
The created agent object
Raises:
ConnectionError: If connection to the backend fails
AgentError: If agent creation fails
"""
# Implementation
Git Workflow
Branching Strategy:
main
: Stable production codedevelop
: Integration branch for featuresfeature/xxx
: Feature branchesfix/xxx
: Bug fix branchesdocs/xxx
: Documentation updates
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
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:
julia -e 'using Pkg; Pkg.activate("julia"); Pkg.update(); Pkg.resolve(); Pkg.instantiate()'
Node.js Dependency Issues
If you encounter issues with Node.js dependencies:
rm -rf node_modules
npm cache clean --force
npm install
Server Connection Issues
If the CLI cannot connect to the Julia server:
Ensure the server is running on the correct port
Check for firewall or network issues
Verify the
.env
configurationCheck server logs for errors
Python Wrapper Issues
If you encounter issues with the Python wrapper:
pip uninstall juliaos
pip install -e ./packages/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