Publishing a Reusable Nim Library with Nimble

Distributing Nim Packages

The primary challenge when sharing Nim code is ensuring that dependencies are handled consistently across different environments. By publishing a library to the Nimble index, you allow other developers to install your code using nimble install <package>, automating the retrieval of source files and dependency resolution.

Prerequisites

• Nim compiler version 1.6 or newer.
• Nimble tool installed (bundled with the standard Nim installation).
• A Git repository initialized for your project.
• Write permissions/account for the target Nimble index (e.g., nimble.directory).

Packaging and Publishing Procedure

1. Organize Source Code

   Place all library logic in a dedicated directory, typically src/. This keeps the root directory clean and allows Nimble to isolate the source files from tests or documentation.

   # src/mylib.nim
   proc hello*(): string = "Hello from mylib!"

2. Configure the .nimble File

   Create a file named <package_name>.nimble in the root directory. This file acts as the manifest for the package manager.

   # mylib.nimble
   version       = "0.1.0"
   author       = "Your Name"
   description  = "A short description of the library"
   license      = "MIT"
   srcDir       = "src"
   dependencies = []

   Risk: The version field must exactly match the Git tag used during release, or the index may reject the upload.

3. Local Validation

   Before publishing, use nimble develop in the repository root. This command installs the package in a way that changes to the source code are immediately reflected without needing a reinstall.

   # Run in terminal
   nimble develop

   Verify the installation by compiling a separate test script:

   # test.nim
   import mylib
   echo hello()

   nim c -r test.nim

4. Version Tagging

   Commit your changes and create a Git tag that corresponds to the version defined in your .nimble file.

   git add .
   git commit -m "Release v0.1.0"
   git tag v0.1.0
   git push origin main --tags

5. Index Publication

   Run the publish command from the root directory. You must be authenticated with the index server via nimble login prior to this step.

   nimble publish

Verification and Diagnostics

To confirm the package is live and usable, perform the following checks:

• Search Check: Run nimble search mylib. The output should display the package name and the correct version number.
• Clean Install: In a temporary directory, run nimble install mylib. Attempt to compile a basic program importing the library to ensure all paths in srcDir were packaged correctly.
• CI Validation: If using a CI pipeline, verify that nimble build and nimble test pass on the specific release tag.

Recovery and Rollback

If a publication error occurs or a buggy version is released, use these recovery paths:

Scenario	Action	Command/Method
Auth Failure	Re-authenticate	nimble login
Version Mismatch	Delete remote tag, fix .nimble, re-tag	git push origin :refs/tags/v0.1.0
Buggy Release	Retract version (Nimble 0.10+)	nimble yank mylib 0.1.0

Limitation: Once a package name is published, it cannot be changed. To rename a library, you must create a new repository and publish it as a new package.