DOCSEARCHbyAlgolia
Submit Docs

Nimble Guide

repository·master·Indexed 23 days ago

https://github.com/nim-lang/nimble

Documentation for Nimble, the package manager for the Nim programming language. Covers package creation using `nimble init`, project structure, dependency management with version selectors, and the use of NimScript for custom tasks and conditional dependencies. Includes guides on configuring `nimble.ini`, running tests, building and installing packages, and publishing to the official packages repository.

Tokens
8.5K
Snippets
39
Records
64
Agent score
80%

What's inside Nimble

  1. Overview of Nimble package manager

    master

    Nimble is the default package manager for the Nim programming language. It is used to manage dependencies, install packages, and handle the development workflow for Nim projects.

    To check which version of Nimble you are currently using, run the following command:

    nimble -v

  2. Understand Nimble's default folder structure

    master

    By default, Nimble stores all installed packages and metadata in $HOME/.nimble.

    • Libraries: Stored in $nimbleDir/pkgs2.
    • Compiled Binaries: Linked in $nimbleDir/bin.

    Note: If a Nimble package provides command-line tools, you must add $nimbleDir/bin to your $PATH to run them. The Nim compiler automatically finds modules in the default directory, allowing you to use import modulename without extra configuration.

  3. Create a Binary package in Nimble

    master

    A package is automatically treated as a binary package if you define at least one value in the bin array within your .nimble file.

    When a user runs nimble install on a binary package:

    1. Nimble builds the specified .nim files.
    2. The resulting binaries are copied to $nimbleDir/pkgs2/pkgname-ver-checksum/.
    3. A symlink is created in $nimbleDir/bin/ (on Windows, a stub .cmd file is created instead).

    Dependencies are automatically installed before the build process begins.

    bin = @["main"]

  4. Automatic Nim Version Management

    master

    Nimble can automatically manage Nim versions to ensure projects use compatible compilers.

    How it works

    When running commands like build or install, Nimble:

    1. Checks the requirements in your .nimble file (e.g., requires "nim >= 2.0.0").
    2. If the system Nim is incompatible, Nimble downloads a prebuilt binary from nim-lang.org.
    3. Caches the binary in ~/.nimble/nim/ for reuse.

    Key Features

    • Per-project versions: Different projects can use different Nim versions.
    • Lock files: The exact Nim version can be pinned in nimble.lock.
    • Automatic downloads: Newer required versions are fetched automatically.

  5. How features work in Nimble (Experimental)

    master

    Features allow for conditional dependency resolution, particularly useful when using the Declarative Parser (activated via --parser:declarative).

    Defining a feature

    Use the feature block in your .nimble file:

    feature "chronos":
  requires "chronos"

    Activating a feature

    1. Via CLI: nimble --features:chronos install
    2. Via dependency: requires "awesomeAsyncPackage[chronos]" (or multiple: [chronos, feature2])

    Checking active features in code

    In your Nim source code, use the following pattern: when defined(features.packageName.featureName):

    # In .nimble
feature "chronos":
  requires "chronos"

# In Nim code
when defined(features.awesomeAsyncPackage.chronos):
  import chronos

  6. Compile with `nim` using a custom Nimble directory

    master

    The Nim compiler does not read .nimble files and cannot resolve dependencies on its own; it only uses the nimblePath feature to find installed packages. While the compiler automatically looks at the default $HOME/.nimble, you must manually specify the path using the --nimblePath:PATH flag if you are using a custom $nimbleDir or local dependencies.

    Important: Always use Nimble to build your package before publishing to ensure that the dependencies specified in your .nimble file are correctly resolved and verified.

  7. Install packages from a URL

    master

    You can install packages directly from a Git or Mercurial repository URL. Nimble will automatically detect the repository type.

    If the .nimble file is located in a subdirectory of the repository, use the ?subdir=<path> query parameter.

    nimble install https://github.com/nimble-test/multi?subdir=alpha

  8. Publish a Nimble package

    master

    Publishing allows users to associate a name with a URL in the official packages repository. There are two methods:

    1. Semi-automatic: Run nimble publish. This requires a GitHub account and a personal access token stored in $nimbleDir/github_api_token.
    2. Manual: Fork the packages repository, add your package entry to packages.json, and submit a pull request.

    You only need to perform the publishing step once per package; you do not need to re-publish for every version increment.

  9. Recommended project structure for Nimble packages

    master

    For a package named foobar, follow this structure to ensure proper imports and testing:

    • LICENSE and README.md: Project documentation.
    • foobar.nimble: The package definition file.
    • src/: The source directory. If you use this, your .nimble file must contain srcDir = "src".
      • src/foobar.nim: The main module, imported via import foobar.
      • src/foobar/: A subdirectory for submodules, e.g., src/foobar/utils.nim is imported via import foobar/utils.
      • src/foobar/private/: A directory for modules you wish to hide from users.
    • tests/: Contains test files and a config.nims file.
    .                   # The root directory of the project
├── LICENSE
├── README.md
├── foobar.nimble   # The project .nimble file
└── src
    └── foobar.nim  # Imported via `import foobar`
└── tests           # Contains the tests
    ├── config.nims
    ├── tfoo1.nim   # First test
    └── tfoo2.nim   # Second test

  11. Install Nimble using koch

    master

    The koch tool is a build tool included in the Nim distribution. You can use it to compile and install Nimble by navigating to your Nim installation directory and running the nimble command through koch. This process clones the Nimble repository, compiles it, and places the binary in Nim's bin directory.

    ./koch nimble