Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท FFI and Tooling

Nimble, Packages and Project Layout in Nim

Learn how Nimble creates projects, declares dependencies and tasks in a .nimble file, installs packages, structures a Nim project, and how version ranges are resolved.

Real programs use libraries, and libraries need a way to be found, versioned and installed. Nim's package manager is Nimble. It ships with the Nim installer and handles project creation, dependencies, tests, tasks and publishing.

Nimble and the Nim compiler are not available on this site, so the commands and files below are read-only examples that you can try on your own machine. The runnable C stand-in at the end implements the core idea of Nimble: checking version constraints.

Creating a project

Text
nimble init hello

Nimble asks a few questions (package type: binary, library or hybrid) and writes a hello.nimble file and a folder layout. A typical binary project looks like this:

Text
hello/
  hello.nimble
  src/
    hello.nim
  tests/
    test1.nim

Source files live in src/. Tests live in tests/, and each file is one test program.

The .nimble file

The package file is written in Nim syntax (the NimScript subset), so it can contain real logic.

NIM
version       = "0.1.0"
author        = "You"
description   = "A small greeting tool"
license       = "MIT"
srcDir        = "src"
bin           = @["hello"]

requires "nim >= 2.0.0"
requires "cligen >= 1.6.0"

requires lines list dependencies with version constraints: >= 1.0, == 1.2.3, ~= 1.2 (compatible with 1.2.x), or a git commit with #head. Nimble resolves them to a single version of each package and downloads them into ~/.nimble/pkgs.

Everyday commands

Command What it does
nimble install cligen Download and install a package
nimble build Compile the binaries in bin
nimble run Build and run
nimble test Compile and run each file in tests/
nimble search json Search the package index
nimble list -i Show installed packages
nimble publish Register a package (needs a git repository and tag)

Version tags in git, such as v0.1.0, are how Nimble knows what a published version means. Packages are listed in the official index (the packages.json file) and are plain git repositories, so private ones work with a URL.

Tasks

You can add custom commands inside the .nimble file with the task template:

NIM
task docs, "Build the documentation":
  exec "nim doc --project --index:on src/hello.nim"

task clean, "Remove build output":
  rmDir "build"

Run them with nimble docs or nimble clean. Hooks (before build, after test) let you run steps around standard commands.

Using a package

NIM
import std/[strutils, os]          # standard library: no install needed
import cligen                      # installed with nimble

proc greet(name = "world") =
  echo "hello, ", name.toUpperAscii

dispatch greet                     # cligen builds the command line from the proc

Standard library modules live under std/. Imports from installed packages are written by package name. Use import mymodule/sub for files inside your project, relative to the source folder.

Version resolution

When two dependencies need the same package, Nimble must find a version that satisfies every constraint. The stand-in checks a version against a >= requirement, comparing major, minor and patch in order:

C C stand-in: does a version satisfy a minimum?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Compare numbers, not strings: as text, "1.10" sorts before "1.9", which is wrong. The next stand-in shows this trap:

C C stand-in: why versions are not strings

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Good habits

  • Pin a lower bound that you tested (>= 1.6.0), not any.
  • Keep a nimble.lock (nimble lock) for applications so builds are repeatable.
  • Put reusable code in a library package and a thin bin on top of it.
  • Run nimble test before publishing; see Testing and Debugging.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file describes a Nim package?

    A .nimble file holds metadata, dependencies and tasks.
  2. 2. What does nimble test run?

    It compiles and runs the files in tests/.
  3. 3. Where do you declare a dependency?

    requires lines list packages with version constraints.
  4. 4. Why compare versions as numbers?

    Lexicographic comparison orders 1.10 before 1.9, which is wrong.

Summary

  • Nimble creates projects, installs dependencies, builds, tests and publishes.
  • The .nimble file uses Nim syntax: metadata, requires, task.
  • Standard library imports use std/; packages are imported by name.
  • Versions are compared numerically; lock files keep builds repeatable.

Next: Testing and Debugging