Getting Started With Nimble
Nimble is Nim's package manager and build system. It's used to install and build libraries that you can use within your own Nim projects, and to build your own Nim projects.
Installing Nimble
Nimble has some runtime dependencies on external tools, these tools are used to download Nimble packages. For instance, if a package is hosted on Github you require to have git installed and added to your environment PATH. Same goes for Mercurial repositories on Bitbucket. Nimble packages are typically hosted in Git repositories so you may be able to get away without installing Mercurial.
Warning: Ensure that you have a fairly recent version of Git installed. If the version is less recent than 1.9.0 then Nimble may have trouble using it.
Installation on Windows
If you installed Nim using the binary installer as described in Getting Started, there is an option during install to install Nimble along with Nim. To check whether it installed, simply run the below from a command prompt:
$ nimble -v
You should see some output such as:
nimble v0.7.4 compiled at 2016-06-15 20:03:45
Installation on Mac OS X, Linux and other Unix based systems
Make sure that you have installed Nim as described in the Getting Started chapter and have added the $nim/bin directory to your PATH environment variable.
In the directory that you downloaded the Nim source code to in the previous chapter, run the following terminal command:
$ nim e install_nimble.nims
This will build Nimble and install it in the $nim/bin directory to make sure it's in your path.
Making sure Nimble is installed correctly
Now that you've installed Nimble, it's a good idea to refresh the package list:
$ nimble refresh
Downloading "Official" package list
Trying https://github.com/nim-lang/packages/raw/master/packages.json...
Done.
Using Nimble
Nimble is used to create packages, install third party packages and build your own programs. There are many different commands and options, which won't all be covered here. For more information on Nimble, please refer to the official documentation.
Creating a new package
To create a new package in your current directory, you can use the nimble init command. This command will ask you a couple of questions about your new package:
$ nimble init
In order to initialise a new Nimble package, I will need to ask you
some questions. Default values are shown in square brackets, press
enter to use them.
Enter package name [first_nimble_package]:
Enter intial version of package [0.1.0]:
Enter your name [Euan T]: Euan T
Enter package description: My first Nimble package!
Enter package license [MIT]:
Enter lowest supported Nim version [0.14.2]:
This will create a single file, with the .nimble extension. The name of this file is the same as the name you chose for your package. The file with contain the details you provided for your package:
# Package
version = "0.1.0"
author = "Euan T"
description = "My first Nimble package!"
license = "MIT"
# Dependencies
requires "nim >= 0.14.2"
There are many more options you can add to this file to describe your project and to add more dependencies on other packages. For more details, please refer to the Creating Packages section of the Nimble documentation.
Installing a Nimble package from the directory
One of the main functions of Nimble is to manage third party dependencies for your projects. In order to install a package, Nimble includes an install command, it also provides commands to search for packages in the registry:
$ nimble search math
linagl:
url: https://bitbucket.org/BitPuffin/linagl (hg)
tags: library, opengl, math, game
description: OpenGL math library
license: CC0
website: https://bitbucket.org/BitPuffin/linagl
extmath:
url: https://github.com/achesak/extmath.nim (git)
tags: library, math, trigonometry
description: Nim math library
license: MIT
website: https://github.com/achesak/extmath.nim
Once you find a package you wish to install from a search, you can install it using the install command:
$ nimble install extmath
Searching in "official" package list...
Downloading https://github.com/achesak/extmath.nim into /tmp/nimble_7370/githubcom_achesakextmathnim using git...
Found tags...
Cloning latest tagged version: v1.2
Cloning into '/tmp/nimble_7370/githubcom_achesakextmathnim'...
remote: Counting objects: 7, done.
remote: Compressing objects: 100% (7/7), done.
remote: Total 7 (delta 0), reused 4 (delta 0), pack-reused 0
Unpacking objects: 100% (7/7), done.
Checking connectivity... done.
Note: checking out '00bbc5b5611a963a2bdde16d19fc0c3c1b050131'.
You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.
If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:
git checkout -b <new-branch-name>
Installing extmath-1.1.0
/tmp/nimble_7370/githubcom_achesakextmathnim/documentation.html -> /Users/euan/.nimble/pkgs/extmath-1.1.0/documentation.html
/tmp/nimble_7370/githubcom_achesakextmathnim/extmath.babel -> /Users/euan/.nimble/pkgs/extmath-1.1.0/extmath.babel
/tmp/nimble_7370/githubcom_achesakextmathnim/extmath.nim -> /Users/euan/.nimble/pkgs/extmath-1.1.0/extmath.nim
/tmp/nimble_7370/githubcom_achesakextmathnim/LICENSE -> /Users/euan/.nimble/pkgs/extmath-1.1.0/LICENSE
/tmp/nimble_7370/githubcom_achesakextmathnim/README -> /Users/euan/.nimble/pkgs/extmath-1.1.0/README
/tmp/nimble_7370/githubcom_achesakextmathnim/extmath.babel -> /Users/euan/.nimble/pkgs/extmath-1.1.0/extmath.babel
extmath installed successfully.
You can also similarly uninstall a package with the uninstall command:
$ nimble uninstall extmath
Looking for extmath (any version)...
Checking reverse dependencies...
The following packages will be removed:
extmath (1.1.0)
Do you wish to continue? [y/N]
y
Removed extmath (1.1.0)
Building a Nimble projects
Once you've finished writing code for your Nimble project, you can easily build it using Nimble. This will install all of your listed dependencies in your package file and compile everything:
$ nimble build
This will build the package in debug mode, in order to build a release mode package with all optimizations, you can use the install command without any arguments inside your package directory:
$ nimble install