v0.4.0

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 that mark each of the Test package's checks with try, 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"]
LevelDeclared byGroupspub matters?
Modulemodule Name { } in a fileitemsno — a package sees all its modules
PackageRux.toml with [Package]files and modulesyes — at the border to other packages
WorkspaceRux.toml with [Workspace]packagesno — membership is not a dependency

Lessons

LessonWhat you will learn
22.1Modulesplit a package across source files and modules
22.2Visibilitychoose what a package shows to others with pub
22.3Packagewhat a manifest says about a package
22.4Dependencydepend on another package
22.5Workspacebuild several packages together
22.6Source librarywrite a library and use it from an executable
22.7Static librarybuild a static library
22.8Shared librarybuild a shared library
22.9Documentationdocument your code with /// comments
22.10Toolingformat, lint, test and document with the rux tool
22.11Unit testswrite #Test functions that throw TestFailure from Expect checks, and run them with rux test
22.12Benchmarkmeasure how long code takes with the Test package's benchmarks

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.