Installing Nimble packages

The installation of Nimble packages is likely the most common task that you’ll use Nimble for. You saw an example of the install command in the previous section.

This command is the primary means of installing packages.

5.5.1 Using the install command

The install command is powerful. It can do any of the following:

 Install packages on your local filesystem

 Install packages from a specified URL

 Install a package by name

 Install a specific version of a package

 Install multiple packages at once

Installing local packages is simple. Just open a new terminal, cd into the directory of your local package (by typing cd /home/user/MyPkg, for example), and execute nimble install.

To install a package from a URL, open a new terminal and execute nimble install <your_url_here>, replacing the <your_url_here> with the URL of the pack-age you want to install. Currently, the URL must point to a non-empty Git or Mercurial repository.

Nimble saves you the trouble of remembering a bunch of URLs for different pack-ages. A package repository that contains a listing of packages created by the Nim com-munity is available. Nimble downloads this listing, which contains some basic information about each package, such as the package’s URL and name. Remember the search command? It searches through this listing, so any of the packages listed in your search results can be installed by specifying their names after the install com-mand. For example, to install the daemonize package seen in the search results in fig-ure 5.4, execute nimble install daemonize.

A specific version of a package can be installed by using the special @ character after the name of a package. For example, to install version 0.0.1 of the daemonize package, execute nimble install [email protected]. Alternatively, instead of a spe-cific version, you can specify a version range. For example, if you want to install the lat-est version that’s greater than version 0.0.1, you can execute nimble install daemonize@>=0.0.1. Specifying a repository revision is also supported by using the # character after the @ character, such as nimble install daemonize@#b4be443.

WARNING: SPECIAL CHARACTERS IN SHELLS Depending on your shell, some of the characters, such as @, >, or =, may be treated as part of the shell’s syntax.

You may need to escape them or quote the package name and version like so:

nimble install "daemonize@>=0.1.0".

Specifying multiple parameters to the install command will cause Nimble to install more than one package. The parameters just need to be separated by a space.

5.5.2 How does the install command work?

To learn about what the install command does, let’s look at the previous example command: nimble install daemonize. Try executing it now if you haven’t already.

You should see output similar to that in figure 5.7.

Nimble’s output is currently rather verbose, but it tries to give as much information about the installation as possible. The output that you see in your version of Nimble may be a bit different from figure 5.7, but the key information should remain the same. The messages shown in figure 5.7 show each of the files from the daemonize package being copied into /Users/dom/.nimble/pkgs/daemonize-0.0.2/.

Scroll up in your terminal window, and you’ll see what Nimble does first: it begins downloading the package. But before that, Nimble needs to know where to download the daemonize package from, and it determines this by consulting the package list.

Figure 5.8 shows the full installation process and its many subprocesses.

The package list is currently hosted in a Git repository, and it can be accessed on GitHub at the following URL: https://github.com/nim-lang/packages. The package-list repository stores a packages.json file that lists metadata for different packages, including each package’s name, URL, description, and more. Nimble can read this list, find the package you specified on the command line, and retrieve that package’s URL. That way Nimble can determine the location of that package’s repository and can easily download it. Figure 5.9 shows how the daemonize package is found in the packages.json file.

Shows the files that are being installed as part of the package.

This wouldn’t be shown without the --verbose flag.

Installation status message

The ^--verbose flag is necessary to show the additional status message.

Destination filename

The filename being copied Figure 5.7 The output of nimble install daemonize

$ nimble install daemonize

https://github.com/rgv151/daemonize.nim Find download URL and repo type for daemonize package

Download the repository

$ git clone https://github.com/rgv151/daemonize.nim

Find ^.nimble file.

Parse it.

Verify version requirements.

Check dependencies.

If dependencies are not installed, install them.

daemonize daemonize.nim daemonize.nimble

~/.nimble/pkgs/daemonize-0.2.0 daemonize.nim

daemonize.nimble Copy

Copy

... ...

Copy files in package directory to installation directory

$ nimble install <dependency>

Figure 5.8 The Nimble installation process

$ nimble install daemonize

packages.json

...

{

"name": "daemonize",

"url": "https://github.com/rgv151/daemonize.nim", "method": "git",

"tags": ["daemonize", "background", "linux"], "description": "This library makes your code run

as a daemon process on Unix-like systems", "license": "MIT",

"web": "https://github.com/rgv151/daemonize.nim"

}, ...

"url": "https://github.com/rgv151/daemonize.nim"

"method": "git"

https://github.com/rgv151/daemonize.nim (git) Find download URL

and repo type for daemonize package

Figure 5.9 Finding information about the daemonize package in the packages.json file

PACKAGE LISTS The package list stored in https://github.com/nim-lang/ pack-ages is the official Nimble package list. As of version 0.7.0, Nimble supports multiple package lists, so you can easily create and use your own package list in conjunction with the official one. The “Configuration” section of the Nim-ble readme explains how this can be done: https://github.com/nim-lang/nimble#configuration.

The download is done using either Git or Mercurial. As part of the download process, Nimble parses the tags on the remote repository and determines which satisfies the version requirements specified by the user. If more than one tag satisfies the version requirements, it picks the highest version. Figure 5.10 shows how Nimble decides which commit of a Nimble package to install.

Once the download is complete, the package’s .nimble file is read, and Nimble verifies the validity of this file. Before installation can commence, the following must be checked:

 The version field specified in the .nimble file must correspond to the version that was tagged on the repository.

 The files that will be installed must follow a specific directory layout.

 The correct dependencies specified in the .nimble file must be installed.

Those are some of the most common checks that Nimble performs. If the first two fail, they’ll result in an error and the package won’t be installed. Missing dependencies will be installed automatically by Nimble. You’ll learn more about these checks in the next section, where I’ll show you how to create your own Nimble package.

Once the package is successfully validated, the installation commences, and Nim-ble copies all the files in the package to ~/.nimNim-ble/pkgs/pkg-ver, where ver is the ver-sion of the package and pkg is the name of the package.

HEAD

Figure 5.10 How Nimble decides which version of a package to install

That’s a simple overview of the process involved in installing a Nimble package.

This process can become more complicated depending on the options specified in the .nimble file.