FluxSharp Package System Guide

Overview

The FluxSharp package system allows you to organize, structure, and reuse code across multiple files. This guide covers how to create, organize, and manage packages effectively.

Basic Concepts
Package Structure
Creating Packages
Importing Packages
Best Practices
Package Organization Patterns
Error Handling
Advanced Patterns

Basic Concepts

What is a Package?

A package in FluxSharp is a collection of related .fsh files that provide specific functionality. Packages are the primary mechanism for code organization and reuse.

Key Principles

Modularity: Each package has a single responsibility
Reusability: Packages can be imported and used in multiple programs
Isolation: Packages maintain their own scope and dependencies
Clarity: Clear naming and structure make packages easy to understand

Package Structure

Minimal Package Structure

project/
├── main.fsh                    # Entry point with Main class
└── packages/
    ├── math/
    │   ├── calculator.fsh      # Core math operations
    │   └── advanced.fsh        # Advanced math functions
    └── utils/
        ├── string.fsh          # String utilities
        └── array.fsh           # Array utilities

Complete Package Structure

project/
├── main.fsh                    # Entry point
├── packages/
│   ├── math/
│   │   ├── core.fsh            # Core operations
│   │   ├── algebra.fsh         # Algebra module
│   │   ├── geometry.fsh        # Geometry module
│   │   └── README.md           # Package documentation
│   ├── utils/
│   │   ├── string.fsh
│   │   ├── array.fsh
│   │   ├── date.fsh
│   │   └── README.md
│   └── database/
│       ├── connection.fsh
│       ├── query.fsh
│       ├── migration.fsh
│       └── README.md
└── examples/
    ├── example1.fsh
    └── example2.fsh

Directory Naming Conventions

packages/
├── math/              # ✅ Lowercase for package names
├── string_utils/      # ✅ Use underscores for multi-word packages
├── DataAccess/        # ❌ Avoid PascalCase for directories
└── db-operations/     # ⚠️ Hyphens work but underscores are preferred

Creating Packages

Step 1: Organize by Functionality

Create a package directory for each distinct set of features:

packages/
├── math/              # All math-related utilities
├── io/                # Input/output operations
├── crypto/            # Cryptographic functions
└── serialization/     # Data serialization

Step 2: Define Package Classes

Each package typically contains one or more related classes:

packages/math/calculator.fsh

public class Calculator {
    public int Add(int a, int b) {
        return a + b;
    }
    
    public int Subtract(int a, int b) {
        return a - b;
    }
    
    public int Multiply(int a, int b) {
        return a * b;
    }
    
    public int Divide(int a, int b) {
        if (b == 0) {
            print("Error: Division by zero");
            return 0;
        }
        return a / b;
    }
}

Step 3: Create Helper Utilities

packages/math/statistics.fsh

public class Statistics {
    public int Sum(int[] numbers) {
        int total = 0;
        int i = 0;
        while (i < numbers.Length) {
            total = total + numbers[i];
            i = i + 1;
        }
        return total;
    }
    
    public int Average(int[] numbers) {
        if (numbers.Length == 0) {
            return 0;
        }
        int total = this.Sum(numbers);
        return total / numbers.Length;
    }
}

Step 4: Document Your Package

packages/math/README.md

# Math Package

Provides mathematical utilities for calculations.

## Classes

### Calculator
- `Add(int a, int b)` - Add two numbers
- `Subtract(int a, int b)` - Subtract two numbers
- `Multiply(int a, int b)` - Multiply two numbers
- `Divide(int a, int b)` - Divide two numbers

### Statistics
- `Sum(int[] numbers)` - Sum all numbers in array
- `Average(int[] numbers)` - Calculate average

## Usage Example

fsh using "packages/math/calculator.fsh"; using "packages/math/statistics.fsh";

public class Main { public void main() { Calculator calc = new Calculator(); int result = calc.Add(5, 3); print(result); } }

```

---

## Importing Packages

### Basic Import

**Using Directive (Recommended)**

fsh using "packages/math/calculator.fsh"; using "packages/utils/string.fsh";

public class Main { public void main() { Calculator calc = new Calculator(); int sum = calc.Add(10, 20); print(sum); } }


**Import Directive (Alternative)**

fsh import "packages/math/calculator.fsh";

public class Main { public void main() { // Same functionality as using } }


### Multiple Imports

fsh // Math package using "packages/math/calculator.fsh"; using "packages/math/statistics.fsh";

// Utilities package using "packages/utils/string.fsh"; using "packages/utils/array.fsh";

// Database package using "packages/database/connection.fsh"; using "packages/database/query.fsh";

public class Main { public void main() { // Use all imported classes } }


### Import Order

fsh // 1. System imports first (if any) // 2. Package imports (organized by module) // 3. Local imports

// Core math using "packages/math/core.fsh";

// Extended math (may depend on core) using "packages/math/advanced.fsh";

// Utilities using "packages/utils/helpers.fsh";

// Main program public class Main { public void main() { // Implementation } }


---

## Best Practices

### 1. Single Responsibility Principle

Each package should handle **one concept**:

✅ Good packages/ ├── http/ # Only HTTP functionality ├── json/ # Only JSON parsing └── crypto/ # Only cryptography

❌ Avoid packages/ └── utilities/ # Too vague, mixes everything


### 2. Clear Naming

fsh // ✅ Clear, descriptive names public class HttpClient { } public class JsonParser { } public class AesEncryption { }

// ❌ Vague names public class Helper { } public class Util { } public class Process { }


### 3. Consistent Naming Convention

fsh // Use PascalCase for class names public class UserManager { }

// Use PascalCase for method names public void CreateUser(string name) { }

// Use lowercase for package/directory names packages/user_management/

// Use underscores in filenames for multi-word files packages/user_management/user_validator.fsh


### 4. Dependency Organization

packages/ ├── base/ # No dependencies │ └── types.fsh ├── utils/ # Depends only on base │ └── helpers.fsh └── services/ # Depends on base and utils └── processor.fsh


**File Dependencies:**

fsh // processor.fsh - Services level using "packages/base/types.fsh"; // ✅ Can import base using "packages/utils/helpers.fsh"; // ✅ Can import utils using "packages/services/other.fsh"; // ✅ Can import same level


### 5. Avoid Circular Dependencies

❌ Bad (Circular) calculator.fsh imports validator.fsh validator.fsh imports calculator.fsh

✅ Good (Linear) main.fsh imports calculator.fsh calculator.fsh imports validator.fsh validator.fsh has no imports (or only imports base)


---

## Package Organization Patterns

### Pattern 1: Functional Packages

Organize by functionality:

packages/ ├── authentication/ ├── authorization/ ├── payments/ ├── notifications/ └── reports/


### Pattern 2: Layered Packages

Organize by architectural layer:

packages/ ├── domain/ # Core business logic ├── application/ # Use cases and services ├── infrastructure/ # External integrations └── presentation/ # UI/API logic


### Pattern 3: Domain-Driven Packages

Organize by business domain:

packages/ ├── user/ │ ├── model.fsh │ ├── service.fsh │ └── repository.fsh ├── product/ │ ├── model.fsh │ ├── service.fsh │ └── repository.fsh └── order/ ├── model.fsh ├── service.fsh └── repository.fsh


### Pattern 4: Feature-Based Packages

Organize by features:

packages/ ├── authentication/ │ ├── login.fsh │ ├── logout.fsh │ └── token.fsh ├── user_profile/ │ ├── view.fsh │ ├── edit.fsh │ └── settings.fsh └── notifications/ ├── email.fsh ├── sms.fsh └── push.fsh


---

## Error Handling

### Common Import Errors

#### 1. File Not Found

fsh using "packages/math/unknown.fsh"; // ❌ Error

Error: IMPORT FILE NOT FOUND Cannot find imported file: 'packages/math/unknown.fsh'


**Solution:**

fsh using "packages/math/calculator.fsh"; // ✅ Correct path


#### 2. Invalid Extension

fsh using "packages/math/readme.txt"; // ❌ Error

Error: INVALID IMPORT FILE File must have .fsh extension: 'readme.txt'


**Solution:**

fsh using "packages/math/calculator.fsh"; // ✅ .fsh extension


#### 3. Circular Import

fsh // file1.fsh using "packages/file2.fsh";

// file2.fsh using "packages/file1.fsh"; // ❌ Error - Circular import


**Solution:** Restructure dependencies:

fsh // base.fsh (no imports) public class Base { }

// file1.fsh using "packages/base.fsh";

// file2.fsh using "packages/base.fsh";


#### 4. Multiple Main Classes

fsh // main.fsh using "packages/math/calculator.fsh";

public class Main { // ✅ Main class here public void main() { } }

// calculator.fsh public class Main { // ❌ Error - Another Main class public void process() { } }


**Solution:** Don't include Main class in packages

fsh // calculator.fsh public class Calculator { // ✅ Regular class, not Main public int Add(int a, int b) { return a + b; } }


---

## Advanced Patterns

### Pattern 1: Package Facade

Create a single entry point for a complex package:

fsh // packages/math/facade.fsh using "packages/math/calculator.fsh"; using "packages/math/statistics.fsh";

public class MathFacade { private Calculator calculator; private Statistics statistics;

public MathFacade() { this.calculator = new Calculator(); this.statistics = new Statistics(); }

public int Add(int a, int b) { return this.calculator.Add(a, b); }

public int GetAverage(int[] numbers) { return this.statistics.Average(numbers); } }


**Usage:**

fsh using "packages/math/facade.fsh";

public class Main { public void main() { MathFacade math = new MathFacade(); int sum = math.Add(5, 3); int avg = math.GetAverage(new int[]{1, 2, 3}); } }


### Pattern 2: Package Initialization

Initialize package resources on startup:

fsh // packages/database/manager.fsh public class DatabaseManager { private bool initialized = false;

public void Initialize() { print("Initializing database..."); // Setup code this.initialized = true; print("Database ready"); }

public bool IsReady() { return this.initialized; } }


**Usage:**

fsh using "packages/database/manager.fsh";

public class Main { public void main() { DatabaseManager db = new DatabaseManager(); db.Initialize();

if (db.IsReady()) { print("Starting application"); } } }


### Pattern 3: Configuration Injection

Pass configuration to packages:

fsh // packages/utils/logger.fsh public class Logger { private string logLevel;

public Logger(string level) { this.logLevel = level; }

public void Log(string message) { print("["); print(this.logLevel); print("] "); print(message); } }


**Usage:**

fsh using "packages/utils/logger.fsh";

public class Main { public void main() { Logger logger = new Logger("INFO"); logger.Log("Application started"); } }


---

## Building and Installing Packages

### FluxSharp Built-in Package Manager

FluxSharp includes a **built-in package manager** directly in the `build.sh` script. Packages are bundled in the compiler binary, so no internet connection is required!

#### Available Built-in Packages

- **sdl2** - SDL2 graphics and input library
- **opengl** - OpenGL graphics rendering
- **stdio** - Standard input/output utilities
- **stdlib** - Standard library functions
- **ncurses** - Terminal UI library
- **sqlite3** - SQL database engine

#### Package Manager Commands

bash

List all available packages

./build.sh pkg list

Get details about a package

./build.sh pkg info sdl2

Install a package (extracts .fsh to ./packages/)

./build.sh pkg install sdl2

Search for packages by keyword

./build.sh pkg search "database"


#### Installing a Package

**Step 1: List available packages**

bash $ ./build.sh pkg list 📦 Available Packages: sdl2 - SDL2 graphics library opengl - OpenGL rendering stdio - Standard I/O functions stdlib - Standard library ncurses - Terminal UI sqlite3 - SQL database


**Step 2: Install the package you need**

bash $ ./build.sh pkg install sdl2 ✅ Package 'sdl2' extracted to ./packages/sdl2/

Files:

graphics.fsh
input.fsh
events.fsh


**Step 3: Use in your program**

fsh using "packages/sdl2/graphics.fsh"; using "packages/sdl2/input.fsh";

public class Main { public void main() { // Your SDL2 code here } }


**Step 4: Compile with build.sh**

bash ./build.sh main.fsh


The compiler automatically:
- ✅ Finds installed packages
- ✅ Processes all imports
- ✅ Links with C libraries (if system libs are installed)
- ✅ Creates executable

#### Package Information

**Get detailed package info:**

bash $ ./build.sh pkg info sdl2

Package: sdl2 Version: 2.26.0 Description: Cross-platform SDL2 graphics and input library

Files:

graphics.fsh (2.1 KB)
input.fsh (1.8 KB)
events.fsh (3.2 KB)

System Requirements: Ubuntu/Debian: sudo apt install libsdl2-dev Fedora/RHEL: sudo dnf install SDL2-devel macOS: brew install sdl2

Example Usage: using "packages/sdl2/graphics.fsh";

public class Main { public void main() { // Create window, handle events, etc. } }


#### System Library Dependencies

Some packages require C libraries to be installed on your system:

| Package | System Command |
|---------|-----------------|
| **sdl2** | `sudo apt install libsdl2-dev` |
| **opengl** | `sudo apt install libgl-dev` |
| **ncurses** | `sudo apt install libncurses-dev` |
| **sqlite3** | `sudo apt install libsqlite3-dev` |

**After installing system libraries**, your FluxSharp programs can use them directly!

### Using build.sh

The FluxSharp compiler provides a `build.sh` script for building and compiling packages. This script handles the complete compilation workflow including package resolution.

#### Basic Usage

bash

Compile a single file

./build.sh main.fsh

Build and output to specific location

./build.sh main.fsh -o bin/myapp

Show help

./build.sh --help


### Creating Local Custom Packages

In addition to built-in packages, you can create your own local packages for code organization.

**Two Types of Packages:**

| Type | Location | Installation | Usage |
|------|----------|--------------|-------|
| **Built-in** | Bundled in fluxc | `./build.sh pkg install <name>` | Installed to `./packages/<name>/` |
| **Custom** | Your project | Manual creation | `using "packages/<name>/file.fsh"` |

#### Creating a Custom Package

**Step 1: Create package directory**

bash mkdir -p packages/myutils


**Step 2: Create package files**

bash

packages/myutils/helpers.fsh

public class StringHelper { public void PrintUpper(string text) { // Implementation } }

packages/myutils/validators.fsh

public class InputValidator { public bool IsValidEmail(string email) { // Implementation } }


**Step 3: Import in your main program**

fsh using "packages/myutils/helpers.fsh"; using "packages/myutils/validators.fsh";

public class Main { public void main() { StringHelper helper = new StringHelper(); InputValidator validator = new InputValidator(); } }


**Step 4: Compile**

bash ./build.sh main.fsh


#### Combining Built-in and Custom Packages

You can use both at the same time!

**First, install built-in packages:**

bash ./build.sh pkg install sdl2 ./build.sh pkg install sqlite3


**Then create custom packages:**

bash mkdir -p packages/game mkdir -p packages/database

Create your custom files

- packages/game/engine.fsh

- packages/database/models.fsh


**Use both together:**

fsh // Built-in packages (installed via pkg) using "packages/sdl2/graphics.fsh"; using "packages/sqlite3/database.fsh";

// Custom packages (created by you) using "packages/game/engine.fsh"; using "packages/database/models.fsh";

public class Main { public void main() { // Use all packages together } }


**Compile once:**

bash ./build.sh main.fsh


### Basic Usage

### Package Management Best Practices

#### FluxSharp Package Model vs Traditional Package Managers

**FluxSharp's Simplified Approach:**

| Feature | FluxSharp | npm/pip | Cargo |
|---------|-----------|---------|-------|
| **Installation** | Just copy files | `npm install` | `cargo add` |
| **Package Registry** | File system | npmjs.com | crates.io |
| **Version Management** | File directories | package.json | Cargo.toml |
| **Dependency Resolution** | Compiler handles it | npm does it | cargo does it |
| **No need for** | Central registry | Central registry | Central registry |

**Why FluxSharp is simpler:**

- ✅ **No installation command** - Just place files in directories
- ✅ **No lockfile** - Dependencies are deterministic (local files)
- ✅ **No version conflicts** - Each project has its own packages
- ✅ **Easy to understand** - It's just `.fsh` files in folders
- ✅ **Works offline** - No internet needed

**Trade-off:**
- You manage multiple local copies of shared packages (like old SVN days)
- Better for closed-source, private projects
- Better for learning and simple projects

#### 1. Local Package Organization

Organize packages in your project directory. The `build.sh` script automatically finds and compiles them:

bash project/ ├── main.fsh # Your main entry point ├── packages/ │ ├── math/ │ │ ├── calculator.fsh # Package file │ │ └── statistics.fsh │ ├── utils/ │ │ ├── helpers.fsh │ │ └── validators.fsh │ └── database/ │ ├── connection.fsh │ └── query.fsh └── build.sh # The compiler & package manager


**That's all you need!** When you run `./build.sh main.fsh`, it:
- Finds all packages
- Processes all imports
- Compiles everything
- Links with runtime
- Creates executable

#### 2. Version Management

Manage package versions by organizing them in directories:

bash packages/ ├── math/ │ ├── v1/ # Older version │ │ └── calculator.fsh │ └── v2/ # Current version │ └── calculator.fsh └── utils/ └── helpers.fsh


**Usage:**

fsh // Use specific version by path using "packages/math/v2/calculator.fsh";


#### 3. Package Documentation

Add a `README.md` in each package directory to document usage and contents

#### 4. Sharing Packages Between Projects

Since packages are just local files, you can easily share them:

**Option 1: Copy Package Directory**

bash

Copy math package from another project

cp -r ../other-project/packages/math ./packages/

Now use it in your project

using "packages/math/calculator.fsh";


**Option 2: Git Submodules (for teams)**

bash

Include shared package as submodule

git submodule add https://github.com/team/flux-math ./packages/math

Use the imported package

using "packages/math/calculator.fsh";


**Option 3: Package Template**

bash

Maintain template packages for quick start

template-packages/ ├── math/ ├── utils/ └── database/

Copy what you need for each project

cp -r template-packages/math ./packages/


### Common Build Scenarios

#### Scenario 1: Build Single Package for Testing

bash

Create test file

cat > test_calculator.fsh << 'EOF' using "packages/math/calculator.fsh";

public class Main { public void main() { Calculator calc = new Calculator(); print(calc.Add(10, 20)); } } EOF

Build and run

./build.sh test_calculator.fsh


#### Scenario 2: Build and Deploy Application

bash #!/bin/bash

deploy.sh

Create deployment directory

mkdir -p build/

Build main application

echo "Building application..." ./build.sh main.fsh -o build/app

Copy packages (for reference)

cp -r packages/ build/packages/

Package for distribution

tar -czf build/fluxsharp-app.tar.gz build/app

echo "✅ Deployment package ready: build/fluxsharp-app.tar.gz"


#### Scenario 3: Build Multiple Targets

bash #!/bin/bash

build-all.sh

TARGETS=("main.fsh" "server.fsh" "client.fsh" "cli.fsh")

for target in "${TARGETS[@]}"; do echo "Building $target..." ./build.sh "$target" -o "bin/${target%.fsh}" echo "✅ Built: bin/${target%.fsh}" done

echo "All builds completed!"


### Troubleshooting Build Issues

#### Issue 1: Package Not Found

Error: IMPORT FILE NOT FOUND Cannot find imported file: 'packages/math/calculator.fsh'


**Solution:**

bash

Check package path exists

ls -la packages/math/calculator.fsh

Verify relative path from main.fsh

pwd # Shows your current directory


#### Issue 2: Circular Dependencies

Error: CIRCULAR IMPORT DETECTED Circular dependency chain: main.fsh → utils.fsh → main.fsh


**Solution:**
Restructure your packages to break the cycle:

packages/ ├── core/ # No dependencies ├── utils/ # Only imports core └── services/ # Imports core and utils


#### Issue 3: Build Fails with Multiple Imports

Error: MULTIPLE MAIN CLASSES DETECTED


**Solution:**
Ensure imported files don't have a Main class:

fsh // ✅ packages/math/calculator.fsh (correct) public class Calculator { // No Main class here }

// ❌ Don't do this in packages public class Main { // Wrong! public void main() { } } ```

Summary

Concept	Description
Package	A collection of related `.fsh` files
Module	A `.fsh` file containing one or more classes
Import	Loading external packages with `using` or `import`
Dependency	Relationship between packages
Facade	Single entry point for complex packages
Build Script	`./build.sh` - Compiles, links packages & manages installations

Next Steps

✅ Review Includes and Main for compilation details
✅ Check C# Imports Update for syntax variations
✅ Study Best Practices for general guidelines
✅ Explore Examples for working code

FluxSharp Package System Guide

Overview

Table of Contents

Basic Concepts

What is a Package?

Key Principles

Package Structure

Minimal Package Structure

Complete Package Structure

Directory Naming Conventions

Creating Packages

Step 1: Organize by Functionality

Step 2: Define Package Classes

Step 3: Create Helper Utilities

Step 4: Document Your Package

List all available packages

Get details about a package

Install a package (extracts .fsh to ./packages/)

Search for packages by keyword

Compile a single file

Build and output to specific location

Show help

packages/myutils/helpers.fsh

packages/myutils/validators.fsh

Create your custom files

- packages/game/engine.fsh

- packages/database/models.fsh

Copy math package from another project

Now use it in your project

Include shared package as submodule

Use the imported package

Maintain template packages for quick start

Copy what you need for each project

Create test file

Build and run

deploy.sh

Create deployment directory

Build main application

Copy packages (for reference)

Package for distribution

build-all.sh

Check package path exists

Verify relative path from main.fsh

Summary

Next Steps

See Also