Part 22: Packages

Every program so far has been one package with one source file. Real projects are bigger: many files, libraries of your own, packages from the registry, sometimes a whole tree of packages worked on together. This part shows how Rux organises all of that — from a module inside one file up to a workspace of several packages — and the rux commands that keep such a project tidy. By the end you can split a program into a library and an executable, decide what the library shows to the world, document it, test it, and measure how fast it is.

What you will learn

• Splitting one package across several files, and grouping names into modules with module A::B { }.
• Choosing what a package shows to other packages with pub, and what it keeps private.
• Reading a Rux.toml manifest, and the four package types it can declare.
• Depending on registry packages and on packages in a folder beside your own.
• Keeping a program and its libraries in one workspace.
• What source, static and shared libraries are, and what each one produces.
• Documenting a public API with /// comments and generating pages with rux doc.
• Formatting, linting and testing a package with rux fmt, rux lint and rux test.
• Writing unit tests as #Test() functions with the Test package's checks, and running them by name.
• Measuring how long code takes with benchmarks, and keeping the measured work from being optimized away.

From module to workspace

Each level groups the one before it:

flowchart LR
    item["Items<br/>functions, types,<br/>constants"] --> mod["Module<br/>`module Shape::Circle { }`<br/>a namespace"]
    mod --> pkg["Package<br/>`Rux.toml` + `Src/`<br/>one `Type`, one `Name`"]
    pkg --> ws["Workspace<br/>a root `Rux.toml`<br/>with `[Workspace]`"]
    pkg -.->|"`[Dependencies]`:<br/>`Path` or `Namespace` + `Version`"| pkg2["Another package"]

Lessons

Before you start

This part leans on Part 4: Functions and Part 6: Types — the libraries here export functions, structs, constructors and methods — and Source library uses a generic function over a slice. Each lesson's package is in the Examples repository's Packages/ folder:

cd Examples/Packages/Module
rux run

Several lessons hold more than one package: the library sits in a folder beside Src/ with its own Rux.toml, and the lesson page shows every file. Workspace is run from its App/ member, the two native library lessons are built with rux build rather than run, and Unit tests is a library whose tests run with rux test.

After this part

Part 23: Compile time is about code chosen while compiling — when, the target and build mode you met as #build in Package, and your own defines. Part 24: Platform then calls native code with extern, which is how a separately built program uses a shared library. This part has no checkpoint project of its own; the next one, Melody, follows Part 24.

For the full rules, see Modules in the Rux Reference, and the packaging guides: Package manifest, Package types and Dependencies. Every command used here is described in the CLI reference.