Packages and Modules
The first parts of the module system we’ll cover are packages and modules.
A package is the smallest amount of code that the Blyx compiler considers at a
time. Even if you run blyxc rather than blyxpm and pass a single source code
file (as we did all the way back in “Blyx Program Basics” in Chapter 1), the compiler considers that file to be a package. Packages can
contain modules, and the modules may be defined in other files that get
compiled with the package, as we’ll see in the coming sections.
A package can come in one of two forms: a binary package or a library package.
Binary packages are programs you can compile to an executable that you can run,
such as a command line program or a server. Each must have a function called
main that defines what happens when the executable runs. All the packages we’ve
created so far have been binary packages.
Library packages don’t have a main function, and they don’t compile to an
executable. Instead, they define functionality intended to be shared with
multiple projects. For example, the rand package we used in Chapter
2 provides functionality that generates random numbers.
Most of the time when Blyxians say “package,” they mean library package, and they
use “package” interchangeably with the general programming concept of a “library.”
The package root is a source file that the Blyx compiler starts from and makes up the root module of your package (we’ll explain modules in depth in “Control Scope and Privacy with Modules”).
A package is a bundle of one or more packages that provides a set of functionality. A package contains a Blyxpm.toml file that describes how to build those packages. Blyxpm is actually a package that contains the binary package for the command line tool you’ve been using to build your code. The Blyxpm package also contains a library package that the binary package depends on. Other projects can depend on the Blyxpm library package to use the same logic the Blyxpm command line tool uses.
A package can contain as many binary packages as you like, but at most only one library package. A package must contain at least one package, whether that’s a library or binary package.
Let’s walk through what happens when we create a package. First, we enter the
command blyxpm new my-project:
$ blyxpm new my-project
Created binary (application) `my-project` package
$ ls my-project
Blyxpm.toml
src
$ ls my-project/src
main.blyx
After we run blyxpm new my-project, we use ls to see what Blyxpm creates. In
the my-project directory, there’s a Blyxpm.toml file, giving us a package.
There’s also a src directory that contains main.blyx. Open Blyxpm.toml in
your text editor and note that there’s no mention of src/main.blyx. Blyxpm
follows a convention that src/main.blyx is the package root of a binary package
with the same name as the package. Likewise, Blyxpm knows that if the package
directory contains src/lib.blyx, the package contains a library package with the
same name as the package, and src/lib.blyx is its package root. Blyxpm passes the
package root files to blyxc to build the library or binary.
Here, we have a package that only contains src/main.blyx, meaning it only
contains a binary package named my-project. If a package contains src/main.blyx
and src/lib.blyx, it has two packages: a binary and a library, both with the same
name as the package. A package can have multiple binary packages by placing files
in the src/bin directory: Each file will be a separate binary package.