Nox

The package manager for the Novus programming language.

Quick install

1. Download the latest version from the realeases tab
2. Run the following command to install gobally (macos) (replace nox_download with the directy of the executable)

   sudo cp "nox_download" /usr/local/bin/nox
   sudo chmod +x /usr/local/bin/nox
   sudo xattr -d com.apple.quarantine /usr/local/bin/nox

3. Run nox help to get started

Usage

# Initialise a new Novus project (auto-installs novus-std)
nox init

# Pull a package by name from the registry
nox pull maths

# Pull a specific version
nox pull maths -v 1.0.0

# Pull a package from a GitHub URL
nox pull https://github.com/MJDaws0n/novus-maths

# Pull a specific branch and commit
nox pull https://github.com/MJDaws0n/novus-maths -b main -c abc123

# List available packages
nox list

# Check installed packages for updates
nox check

# Remove a package
nox remove maths

# Show help
nox help

How It Works

Nox pulls packages from GitHub repositories into a lib/ directory in your project. Each package gets its own folder using the library name (registry name), not the repository name.

Installed packages are tracked in libraries.conf with version, branch, commit, and version constraint information.

nox init

Creates a new project with main.nov, lib/, and libraries.conf. Automatically pulls the novus-std standard library. If run in an existing project, installs any missing packages listed in libraries.conf (like npm install).

my_project/
├── main.nov
├── libraries.conf        ← tracks installed packages
├── lib/
│   ├── novus-std/         ← auto-installed standard library
│   ├── maths/             ← pulled with: nox pull maths
│   └── ...
└── novus

You can then import from pulled packages in your Novus code:

import lib/novus-std/lib/standard_lib;
import lib/novus-std/lib/standard_lib_macos_silicon;
import lib/maths/main;

Note: Due to a Novus compiler limitation (#if blocks in imported files don't export functions), platform selection requires manually changing the import in each loader. This will be automated once the compiler supports conditional exports.

libraries.conf

When you pull packages, Nox automatically creates and maintains a libraries.conf file that tracks:

• Package name, URL, version, branch, and commit — for reproducible builds
• Min/max version constraints — for dependency compatibility

# libraries.conf - Nox package manifest
# Auto-generated by nox

installed=novus-std,maths

pkg:novus-std:url=https://github.com/MJDaws0n/Novus
pkg:novus-std:version=0.1.1
pkg:novus-std:branch=main
pkg:novus-std:commit=4dbd69c...
pkg:novus-std:min=*
pkg:novus-std:max=*

pkg:maths:url=https://github.com/MJDaws0n/novus-maths
pkg:maths:version=1.0.0
pkg:maths:branch=main
pkg:maths:commit=aeb0d9f...
pkg:maths:min=*
pkg:maths:max=*

When you pull a package that has its own libraries.conf, Nox automatically pulls all of its dependencies too. Nox scans nested libraries.conf files throughout the package tree. If there are version conflicts, Nox will warn you.

Package Registry

Packages can be pulled by name (e.g. nox pull maths) using the built-in registry. The registry maps short names to GitHub URLs and is hosted in this repo at registry.txt.

The registry supports versioned entries so you can pull specific versions:

# Base entry (latest)
maths=https://github.com/MJDaws0n/novus-maths
# Version info
maths:latest=1.0.0
# Specific version with branch and commit
maths@1.0.0=https://github.com/MJDaws0n/novus-maths|main|

Available Packages

Look in registry.txt

Adding a Package

To add your package to the registry, submit a PR editing registry.txt with:

your-package=https://github.com/your-username/your-repo
your-package:latest=1.0.0
your-package@1.0.0=https://github.com/your-username/your-repo|main|<commit>

Flags

Flag	Description
--no-depth	Clone full git history instead of shallow (default: --depth 1)
-v <version>	Pull a specific version from the registry
-b <branch>	Clone from a specific branch
-c <commit>	Checkout a specific commit after cloning

Requirements

• Git (installed via Xcode Command Line Tools)
• Internet connection (for pulling packages and fetching registry)

Testing Requirements for Official Libraries

All official Nox libraries must include test files for every supported operating system and CPU architecture. Tests live inside each library directory using the naming convention:

lib/<library>/tests_<os>_<arch>.nov

For example:

lib/std/
├── tests_darwin_arm64.nov
├── tests_linux_amd64.nov
├── tests_linux_arm64.nov
├── tests_windows_amd64.nov
└── tests_windows_x86.nov

What must be tested

• Every custom function that uses inline assembly instructions (e.g. mov, syscall, getreg, win_call) must have at least one test covering it.
• Testing pure Novus functions (no assembly) is strongly recommended but not required.

How to run tests

Each test file is a standalone Novus program with a main() entry point. Compile and run it on the target platform:

novus lib/std/tests_darwin_arm64.nov
./build/darwin_arm64/std_tests_darwin_arm64

Tests do not have to be run natively. You can use:

• Virtual machines (e.g. UTM, QEMU, VirtualBox) for other operating systems
• Docker containers for Linux architectures (docker buildx --platform linux/amd64 or linux/arm64)
• CPU emulation (e.g. QEMU user-mode) for cross-architecture testing

Test file structure

Test files should print [PASS] or [FAIL] for each test case and exit with code 0 on success or 1 on failure:

module my_lib_tests_darwin_arm64;
import main;

fn main(argc: i32, argv: u64) -> i32 {
    let fails: i32 = 0;
    // ... test assertions ...
    if (fails > 0) { return 1; }
    return 0;
}

Built With

Nox is written entirely in Novus, the language it serves. It uses a folder-based library structure with cross-platform core modules and platform-specific implementations, and shells out to git for cloning and curl for fetching the registry.