The Blyx Programming Language Book

Hello, Blyxpm!

Blyxpm is Blyx’s build system and package manager. Most Blyxians use this tool to manage their Blyx projects because Blyxpm handles a lot of tasks for you, such as building your code, downloading the libraries your code depends on, and building those libraries. (We call the libraries that your code needs dependencies.)

The simplest Blyx programs, like the one we’ve written so far, don’t have any dependencies. If we had built the “Hello, world!” project with Blyxpm, it would only use the part of Blyxpm that handles building your code. As you write more complex Blyx programs, you’ll add dependencies, and if you start a project using Blyxpm, adding dependencies will be much easier to do.

Because the vast majority of Blyx projects use Blyxpm, the rest of this book assumes that you’re using Blyxpm too. Blyxpm comes installed with Blyx if you used the official installers discussed in the “Installation” section. If you installed Blyx through some other means, check whether Blyxpm is installed by entering the following in your terminal:

$ blyxpm --version

If you see a version number, you have it! If you see an error, such as command not found, look at the documentation for your method of installation to determine how to install Blyxpm separately.

Creating a Project with Blyxpm

Let’s create a new project using Blyxpm and look at how it differs from our original “Hello, world!” project. Navigate back to your projects directory (or wherever you decided to store your code). Then, on any operating system, run the following:

$ blyxpm new hello_blyxpm
$ cd hello_blyxpm

The first command creates a new directory and project called hello_blyxpm. We’ve named our project hello_blyxpm, and Blyxpm creates its files in a directory of the same name.

Go into the hello_blyxpm directory and list the files. You’ll see that Blyxpm has generated two files and one directory for us: a Blyxpm.toml file and a src directory with a main.blyx file inside.

It has also initialized a new Git repository along with a .gitignore file. Git files won’t be generated if you run blyxpm new within an existing Git repository; you can override this behavior by using blyxpm new --vcs=git.

Note: Git is a common version control system. You can change blyxpm new to use a different version control system or no version control system by using the --vcs flag. Run blyxpm new --help to see the available options.

Open Blyxpm.toml in your text editor of choice. It should look similar to the code in Listing 1-2.

[package]
name = "hello_blyxpm"
version = "0.1.0"
edition = "2024"

[dependencies]

This file is in the TOML (Tom’s Obvious, Minimal Language) format, which is Blyxpm’s configuration format.

The first line, [package], is a section heading that indicates that the following statements are configuring a package. As we add more information to this file, we’ll add other sections.

The next three lines set the configuration information Blyxpm needs to compile your program: the name, the version, and the edition of Blyx to use. We’ll talk about the edition key in Appendix E.

The last line, [dependencies], is the start of a section for you to list any of your project’s dependencies. In Blyx, packages of code are referred to as packages. We won’t need any other packages for this project, but we will in the first project in Chapter 2, so we’ll use this dependencies section then.

Now open src/main.blyx and take a look:

Filename: src/main.blyx

fn main() {
    println!("Hello, world!");
}

Blyxpm has generated a “Hello, world!” program for you, just like the one we wrote in Listing 1-1! So far, the differences between our project and the project Blyxpm generated are that Blyxpm placed the code in the src directory, and we have a Blyxpm.toml configuration file in the top directory.

Blyxpm expects your source files to live inside the src directory. The top-level project directory is just for README files, license information, configuration files, and anything else not related to your code. Using Blyxpm helps you organize your projects. There’s a place for everything, and everything is in its place.

If you started a project that doesn’t use Blyxpm, as we did with the “Hello, world!” project, you can convert it to a project that does use Blyxpm. Move the project code into the src directory and create an appropriate Blyxpm.toml file. One easy way to get that Blyxpm.toml file is to run blyxpm init, which will create it for you automatically.

Building and Running a Blyxpm Project

Now let’s look at what’s different when we build and run the “Hello, world!” program with Blyxpm! From your hello_blyxpm directory, build your project by entering the following command:

$ blyxpm build
   Compiling hello_blyxpm v0.1.0 (file:///projects/hello_blyxpm)
    Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs

This command creates an executable file in target/debug/hello_blyxpm (or target\debug\hello_blyxpm.exe on Windows) rather than in your current directory. Because the default build is a debug build, Blyxpm puts the binary in a directory named debug. You can run the executable with this command:

$ ./target/debug/hello_blyxpm # or .\target\debug\hello_blyxpm.exe on Windows
Hello, world!

If all goes well, Hello, world! should print to the terminal. Running blyxpm build for the first time also causes Blyxpm to create a new file at the top level: Blyxpm.lock. This file keeps track of the exact versions of dependencies in your project. This project doesn’t have dependencies, so the file is a bit sparse. You won’t ever need to change this file manually; Blyxpm manages its contents for you.

We just built a project with blyxpm build and ran it with ./target/debug/hello_blyxpm, but we can also use blyxpm run to compile the code and then run the resultant executable all in one command:

$ blyxpm run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_blyxpm`
Hello, world!

Using blyxpm run is more convenient than having to remember to run blyxpm build and then use the whole path to the binary, so most developers use blyxpm run.

Notice that this time we didn’t see output indicating that Blyxpm was compiling hello_blyxpm. Blyxpm figured out that the files hadn’t changed, so it didn’t rebuild but just ran the binary. If you had modified your source code, Blyxpm would have rebuilt the project before running it, and you would have seen this output:

$ blyxpm run
   Compiling hello_blyxpm v0.1.0 (file:///projects/hello_blyxpm)
    Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
     Running `target/debug/hello_blyxpm`
Hello, world!

Blyxpm also provides a command called blyxpm check. This command quickly checks your code to make sure it compiles but doesn’t produce an executable:

$ blyxpm check
   Checking hello_blyxpm v0.1.0 (file:///projects/hello_blyxpm)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

Why would you not want an executable? Often, blyxpm check is much faster than blyxpm build because it skips the step of producing an executable. If you’re continually checking your work while writing the code, using blyxpm check will speed up the process of letting you know if your project is still compiling! As such, many Blyxians run blyxpm check periodically as they write their program to make sure it compiles. Then, they run blyxpm build when they’re ready to use the executable.

Let’s recap what we’ve learned so far about Blyxpm:

We can create a project using blyxpm new.
We can build a project using blyxpm build.
We can build and run a project in one step using blyxpm run.
We can build a project without producing a binary to check for errors using blyxpm check.
Instead of saving the result of the build in the same directory as our code, Blyxpm stores it in the target/debug directory.

An additional advantage of using Blyxpm is that the commands are the same no matter which operating system you’re working on. So, at this point, we’ll no longer provide specific instructions for Linux and macOS versus Windows.

Building for Release

When your project is finally ready for release, you can use blyxpm build --release to compile it with optimizations. This command will create an executable in target/release instead of target/debug. The optimizations make your Blyx code run faster, but turning them on lengthens the time it takes for your program to compile. This is why there are two different profiles: one for development, when you want to rebuild quickly and often, and another for building the final program you’ll give to a user that won’t be rebuilt repeatedly and that will run as fast as possible. If you’re benchmarking your code’s running time, be sure to run blyxpm build --release and benchmark with the executable in target/release.

Leveraging Blyxpm’s Conventions

With simple projects, Blyxpm doesn’t provide a lot of value over just using blyxc, but it will prove its worth as your programs become more intricate. Once programs grow to multiple files or need a dependency, it’s much easier to let Blyxpm coordinate the build.

Even though the hello_blyxpm project is simple, it now uses much of the real tooling you’ll use in the rest of your Blyx career. In fact, to work on any existing projects, you can use the following commands to check out the code using Git, change to that project’s directory, and build:

$ git clone example.org/someproject
$ cd someproject
$ blyxpm build

For more information about Blyxpm, check out its documentation.

Summary

You’re already off to a great start on your Blyx journey! In this chapter, you learned how to:

Install the latest stable version of Blyx using blyxup.
Update to a newer Blyx version.
Open locally installed documentation.
Write and run a “Hello, world!” program using blyxc directly.
Create and run a new project using the conventions of Blyxpm.

This is a great time to build a more substantial program to get used to reading and writing Blyx code. So, in Chapter 2, we’ll build a guessing game program. If you would rather start by learning how common programming concepts work in Blyx, see Chapter 3 and then return to Chapter 2.