How To Install Nimble Cabinets

Nimble

Nimble is a beta-grade package director for the Nim programming language.

Interested in learning how to create a bundle? Skip directly to that department hither.

Contents

• Requirements
• Installation
• Nimble's binder structure and packages
• Nimble usage
  • nimble refresh
  • nimble install
  • nimble uninstall
  • nimble build
  • nimble c
  • nimble list
  • nimble search
  • nimble path
  • nimble init
  • nimble publish
  • nimble tasks
  • nimble dump
• Configuration
• Creating Packages
  • The new NimScript format
  • Libraries
  • Binary packages
  • Hybrids
  • Dependencies
  • Nim compiler
  • Versions
• Submitting your package to the bundle list.
• .nimble reference
  • [Bundle]
    • Required
    • Optional
  • [Deps]/[Dependencies]
    • Optional
• Troubleshooting
• Contribution
• About

Requirements

Nimble has some runtime dependencies on external tools, these tools are used to download Nimble packages. For example, if a package is hosted on Github you require to accept 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 abroad without installing Mercurial.

Warning: Ensure that you have a fairly recent version of Git installed. If the version is less contempo than 1.ix.0 then Nimble may have trouble using it. Come across this issue for more than info.

Installation

Nimble is now bundled with Nim (since Nim version 0.xv.0). This ways that you should take Nimble installed already, as long as you have the latest version of Nim installed as well. Because of this you likely do non demand to install Nimble manually.

Merely in instance you yet desire to install Nimble manually, you tin follow the following instructions.

In that location are two ways to install Nimble manually. The offset is using the install_nimble.nims script included in the Nim distribution and repository. Simply execute this to install Nimble.

            nim e install_nimble.nims                      

This will clone the Nimble repository, compile Nimble and copy it into Nim'south bin directory.

The second approach is to install Nimble equally a Nimble package. You can do this by compiling Nimble, then running nimble install in Nimble's directory.

            git clone https://github.com/nim-lang/nimble.git cd nimble nim c src/nimble src/nimble install                      

Notation for Windows users: Y'all volition need to rename nimble.exe afterward compilation to something else similar nimble1.exe, then run src\nimble1.exe install.

This will install Nimble to the default Nimble packages location: ~/.nimble/pkgs. The binary volition be installed to ~/.nimble/bin, so you volition need to add this directory to your PATH.

Nimble's binder structure and packages

Nimble stores everything that has been installed in ~/.nimble on Unix systems and in your $home/.nimble on Windows. Libraries are stored in $nimbleDir/pkgs, and binaries are stored in $nimbleDir/bin. Virtually Nimble packages will provide .nim files and some documentation. The Nim compiler is enlightened of Nimble and will automatically find the modules so yous can import modulename and have that working without additional setup.

However, some Nimble packages can provide boosted tools or commands. If y'all don't add their location ($nimbleDir/bin) to your $PATH they will non work properly and you won't be able to run them.

Nimble usage

Once yous have Nimble installed on your system you lot can run the nimble command to obtain a list of available commands.

nimble refresh

The refresh command is used to fetch and update the list of Nimble packages (see beneath). There is no automated update mechanism, so you need to run this yourself if yous need to refresh your local list of known available Nimble packages. Example:

            $ nimble refresh Downloading package list from https://.../packages.json Done.                      

Some commands may remind you to run nimble refresh or will run it for y'all if they fail.

Yous tin can too optionally supply this control with a URL if you would like to use a 3rd-party package list.

Package lists can be specified in Nimble's config. Take a look at the config section beneath to run across how to practice this.

nimble install

The install control volition download and install a package. Y'all need to pass the proper name of the package (or packages) you desire to install. If any of the packages depend on other Nimble packages Nimble volition also install them. Example:

            $ nimble install nake Downloading nake into /tmp/nimble/nake... Executing git... ... nake installed successfully                      

Nimble always fetches and installs the latest version of a package. Note that latest version is divers as the latest tagged version in the git (or hg) repository, if the bundle has no tagged versions then the latest commit in the remote repository will be installed. If you already have that version installed Nimble will inquire you lot whether you wish information technology to overwrite your local copy.

You tin can force Nimble to download the latest commit from the package'due south repo, for instance:

            $ nimble install nimgame@#caput                      

This is of class git specific, for hg use tip instead of head. A branch, tag, or commit hash may besides be specified in the place of caput.

Instead of specifying a VCS branch you may as well specify a version range, for example:

            $ nimble install nimgame@"> 0.5"                      

In this case a version which is greater than 0.5 volition exist installed.

If you don't specify a parameter and there is a package.nimble file in your current working directory and then Nimble will install the packet residing in the current working directory. This can be useful for developers who are testing locally their .nimble files before submitting them to the official parcel listing. Meet the Creating Packages section for more info on this.

A URL to a repository can also exist specified, Nimble will automatically notice the type of the repository that the url points to and install it.

nimble uninstall

The uninstall command volition remove an installed package. Attempting to remove a package which other packages depend on is disallowed and will event in an error. You lot must currently manually remove the reverse dependencies first.

Similar to the install control you can specify a version range, for instance:

            $ nimble uninstall nimgame@0.5                      

nimble build

The build control is by and large used by developers who desire to test building their .nimble packet. This command volition build the packet in debug mode, without installing anything. The install control will build the package in release mode instead.

nimble c

The c (or compile, js, cc, cpp) command can be used by developers to compile private modules inside their bundle. All options passed to Nimble will also be passed to the Nim compiler during compilation.

Nimble will utilize the backend specified in the package'southward .nimble file if the command c or compile is specified. The more than specific js, cc, cpp can be used to override that.

nimble list

The list command will display the known list of packages bachelor for Nimble. An optional --ver parameter tin be specified to tell Nimble to query remote git repositories for the list of versions of the packages and to then impress the versions. Please note still that this can be wearisome equally each parcel must be queried separately.

nimble search

If you don't want to go through the whole output of the list command you can use the search control specifying equally parameters the package name and/or tags you want to filter. Nimble will await into the known list of available packages and display only those that lucifer the specified keywords (which tin can be substrings). Example:

            $ nimble search math linagl:   url:         https://bitbucket.org/BitPuffin/linagl (hg)   tags:        library, opengl, math, game   description: OpenGL math library   license:     CC0  extmath:   url:         git://github.com/achesak/extmath.nim (git)   tags:        library, math, trigonometry   description: Nim math library   license:     MIT                      

Searches are case insensitive.

An optional --ver parameter can be specified to tell Nimble to query remote git repositories for the list of versions of the packages and to then print the versions. Please note yet that this can be wearisome as each bundle must be queried separately.

nimble path

The nimble path command will show the absolute path to the installed packages matching the specified parameters. Since in that location can exist many versions of the same package installed, the path command will ever show the latest version. Example:

            $ nimble path argument_parser /dwelling/user/.nimble/pkgs/argument_parser-0.ane.two                      

Nether Unix y'all can use backticks to quickly access the directory of a parcel, which tin exist useful to read the arranged documentation. Example:

            $ pwd /usr/local/bin $ cd `nimble path argument_parser` $ less README.md                      

nimble init

The nimble init command volition start a unproblematic wizard which will create a quick .nimble file for your project.

As of version 0.vii.0, the .nimble file that this command creates volition use the new NimScript format. Check out the Creating Packages section for more info.

nimble publish

Publishes your Nimble packet to the official Nimble package repository.

Note: Requires a valid Github account.

nimble tasks

For a nimble package in the current working directory, list the tasks which that package defines. This is only supported for packages utilising the new nimscript .nimble files.

nimble dump

Outputs information about the parcel in the electric current working directory in an ini-compatible format. Useful for tools wishing to read metadata about Nimble packages who do not desire to use the NimScript evaluator.

Configuration

At startup Nimble will try to read ~/.config/nimble/nimble.ini on Linux (on Windows it will try to read C:\Users\<YourUser>\AppData\Roaming\nimble\nimble.ini).

The format of this file corresponds to the ini format with some Nim enhancements. For case:

              nimbleDir              = r                "C:\Nimble\"                            [PackageList]              proper name              =                              "CustomPackages"                            url              =                              "http://mydomain.org/packages.json"                          

You can currently configure the following in this file:

• nimbleDir - The directory which nimble uses for parcel installation. Default: ~/.nimble/
• chcp - Whether to alter the current code folio when executing Nim application packages. If truthful this will add chcp 65001 to the .cmd stubs generated in ~/.nimble/bin/. Default: true
• [PackageList] + name + url - You tin employ this department to specify a new custom package listing. Multiple package lists can be specified. Nimble defaults to the "Official" package listing, you can override it past specifying a [PackageList] section named "official". Multiple URLs can be specified under each section, Nimble volition attempt each in succession if downloading from the beginning fails.
• cloneUsingHttps - Whether to supervene upon whatever git:// within URLs with https://. Default: true
• httpProxy - The URL of the proxy to utilize when downloading package listings. Nimble will also endeavour to read the http_proxy and https_proxy environment variables. Default: ""

Creating Packages

Nimble works on git repositories equally its chief source of packages. Its list of packages is stored in a JSON file which is freely accessible in the nim-lang/packages repository. This JSON file provides nimble with the required Git URL to clone the package and install information technology. Installation and build instructions are independent inside a ini-style file with the .nimble file extension. The nimble file shares the package's name, i.east. a package named "foobar" should have a corresponding foobar.nimble file.

These files specify data about the package including its name, author, license, dependencies and more. Without ane Nimble is not able to install a packet.

A .nimble file tin can be created easily using Nimble'south init control. This command will ask you a bunch of questions about your package, then generate a .nimble file for you.

Note: As of version 0.7.0, the init command generates .nimble files using the new NimScript format. Have a look at the next section for more information.

A bare minimum .nimble file follows:

              [Packet]              name              =                              "ProjectName"                            version              =                              "0.1.0"                            writer              =                              "Your Proper noun"                            description              =                              "Example .nimble file."                            license              =                              "MIT"                            [Deps]              Requires:                              "nim >= 0.10.0"                          

You may omit the dependencies entirely, merely specifying the lowest version of the Nim compiler required is recommended.

Nimble currently supports installation of packages from a local directory, a git repository and a mercurial repository. The .nimble file must exist present in the root of the directory or repository existence installed.

The new NimScript format

Warning: This characteristic is however very experimental. You lot are encouraged to try it, just be aware that it may change significantly in the future or may even exist removed completely!

Version 0.7.0 of Nimble introduces support for evaluating .nimble files as Nim code. This means that you tin define metadata about your bundle using the Nim programming language.

Because of Nim'southward flexibility the definitions remain declarative. With the added power of using the Nim language to enrich your package specification. For example, you tin define dependencies for specific platforms using Nim's when argument.

The ini instance above looks like this in the NimScript format:

              # Package              version     =              "0.ane.0"              author      =              "Your Proper name"              description =              "Example .nimble file."              license     =              "MIT"              # Deps              requires              "nim >= 0.x.0"            

The format is indeed very similar to the ini format. Another bully feature is the power to define custom Nimble packet-specific commands. These are divers in the .nimble files of grade.

              job              hello,              "This is a how-do-you-do job"              :              echo("Hello World!")

You lot can so execute nimble hello, which volition result in the following output:

            Executing task hello in /Users/user/projects/pkg/pkg.nimble Hello World!                      

You tin place any Nim code inside these tasks. As long every bit that code does not admission the FFI. The nimscript module in Nim'south standard library defines additional functionality such equally the ability to execute external processes which makes this feature very powerful.

Y'all can also check what tasks are supported by the parcel in the current directory past using the tasks command.

Nimble provides an API which adds fifty-fifty more functionality. For case, you can specify pre and mail hooks for any Nimble control (including commands that you lot define yourself). To practise this you can add something like the post-obit:

              earlier              hello:              echo("About to call hello!")

That will result in the post-obit output when nimble hello is executed (you must also specify the task shown above).

            Executing task hello in /Users/user/projects/pkg/pkg.nimble About to call how-do-you-do! Hello World!                      

Like to this an later on block is also available for post hooks, which are executed after Nimble finished executing a command. Yous can also return false from these blocks to end further execution.

The nimscriptapi.nim module specifies this and includes other definitions which are also useful. Take a wait at it for more data.

Libraries

Library packages are likely the well-nigh popular class of Nimble packages. They are meant to be used by other library packages or the ultimate binary packages.

When nimble installs a library it will copy all the files in the packet into $nimbleDir/pkgs/pkgname-ver. It's up to the package creator to brand sure that the package directory layout is correct, this is so that users of the packet can correctly import the package.

By convention, it is suggested that the layout be as follows. The directory layout is determined by the nature of your package, that is, whether your packet exposes only 1 module or multiple modules.

If your package exposes simply a single module, then that module should exist present in the root directory (the directory with the .nimble file) of your git repository, it is recommended that in this example you lot proper noun that module whatever your parcel's name is. A good case of this is the jester bundle which exposes the jester module. In this case the jester bundle is imported with import jester.

If your parcel exposes multiple modules then the modules should exist in a PackageName directory. This will let for a sure measure of isolation from other packages which expose modules with the same names. In this case the packet's modules will exist imported with import PackageName/module.

Yous are complimentary to combine the two approaches described.

In regards to modules which yous do not wish to be exposed. You lot should identify them in a PackageName/private directory. Your modules may so import these private modules with import PackageName/private/module. This directory structure may exist enforced in the hereafter.

All files and folders in the directory of where the .nimble file resides will be copied equally-is, you can however skip some directories or files by setting the SkipDirs, SkipFiles or SkipExt options in your .nimble file. Directories and files tin can also be specified on a whitelist basis, if you specify either of InstallDirs, InstallFiles or InstallExt then Nimble will only install the files specified.

Binary packages

These are application packages which require building prior to installation. A package is automatically a binary package equally soon as it sets at to the lowest degree one bin value, similar so:

              bin              =                              "primary"                            # NimScript config expects a seq instead, e.thousand. @["main"]            

In this case when nimble install is invoked, nimble will build the principal.nim file, copy it into $nimbleDir/pkgs/pkgname-ver/ and afterwards create a symlink to the binary in $nimbleDir/bin/. On Windows a stub .bat file is created instead.

Other files will be copied in the same manner as they are for library packages.

Binary packages should not install .nim files so you lot should include SkipExt = "nim" in your .nimble file, unless you intend for your package to be a binary/library combo which is fine.

Dependencies are automatically installed before building. Before publishing your package you lot should ensure that the dependencies you specified are correct. You lot can do this past running nimble build or nimble install in the directory of your package.

Hybrids

One matter to note well-nigh library and binary package hybrids is that your binary may share the proper noun of the bundle. This will mean that you will not exist able to put your .nim files in a pkgname directory. The reason you will not be able to do this is because binaries on some operating systems practise non have an extension so they will disharmonism with a directory of the same proper name.

The current convention to go around this problem is to append pkg to the name as is washed for nimble.

Dependencies

Dependencies are specified under the [Deps] section in a nimble file. The requires key field is used to specify them. For example:

              [Deps]              Requires:                              "nim >= 0.10.0, jester > 0.1 & <= 0.v"                          

Dependency lists support version ranges. These versions may either be a concrete version similar 0.i, or they may contain any of the less-than (<), greater-than (>), less-than-or-equal-to (<=) and greater-than-or-equal-to (>=). 2 version ranges may be combined using the & operator for example: > 0.2 & < one.0 which will install a package with the version greater than 0.2 and less than 1.0.

Specifying a concrete version as a dependency is not a good idea because your package may stop up depending on ii unlike versions of the same parcel. If this happens Nimble will reject to install the package. Similarly y'all should not specify an upper-bound every bit this tin can lead to a similar issue.

In improver to versions y'all may also specify git/hg tags, branches and commits. These have to exist concrete nevertheless. This is washed with the # character, for case: jester#head. Which will make your package depend on the latest commit of Jester.

Nim compiler

The Nim compiler cannot read .nimble files. Its knowledge of Nimble is express to the nimblePaths feature which allows it to apply packages installed in Nimble'southward package directory when compiling your software. This ways that it cannot resolve dependencies, and it tin can simply use the latest version of a package when compiling.

When Nimble builds your package it actually executes the Nim compiler. Information technology resolves the dependencies and feeds the path of each package to the compiler so that it knows precisely which version to use.

This means that you tin can safely compile using the compiler when developing your software, but you should utilize nimble to build the packet before publishing information technology to ensure that the dependencies you specified are right.

Versions

Versions of cloned packages via git or mercurial are adamant through the repository's tags.

When installing a packet which needs to be downloaded, after the download is complete and if the package is distributed through a VCS, nimble volition bank check the cloned repository's tags list. If no tags exist, nimble will simply install the Head (or tip in mercurial) of the repository. If tags be, nimble volition attempt to look for tags which resemble versions (e.k. v0.1) and volition then notice the latest version out of the available tags, once it does so it will install the package after checking out the latest version.

You can forcefulness the installation of the HEAD of the repository by specifying #caput after the package proper name in your dependency list.

Submitting your packet to the bundle list.

Nimble's packages listing is stored on github and everyone is encouraged to add together their own packages to it! Take a look at nim-lang/packages to learn more than.

.nimble reference

[Bundle]

Required

• proper name - The name of the package. (This is not required in the new NimScript format)
• version - The current version of this packet. This should be incremented earlier tagging the current version using git tag or hg tag.
• writer - The name of the author of this package.
• description - A cord describing the package.
• license - The proper noun of the license in which this parcel is licensed nether.

Optional

• SkipDirs - A list of directory names which should exist skipped during installation, separated by commas.
• SkipFiles - A list of file names which should be skipped during installation, separated by commas.
• SkipExt - A listing of file extensions which should exist skipped during installation, the extensions should be specified without a leading . and should be separated by commas.
• InstallDirs - A list of directories which should exclusively be installed, if this selection is specified nil else will exist installed except the dirs listed hither, the files listed in InstallFiles, the files which share the extensions listed in InstallExt, the .nimble file and the binary (if bin is specified). Separated by commas.
• InstallFiles - A listing of files which should be exclusively installed, this complements InstallDirs and InstallExt. But the files listed here, directories listed in InstallDirs, files which share the extension listed in InstallExt, the .nimble file and the binary (if bin is specified) volition be installed. Separated by commas.
• InstallExt - A list of file extensions which should be exclusively installed, this complements InstallDirs and InstallFiles. Separated by commas.
• srcDir - Specifies the directory which contains the .nim source files. Default: The directory in which the .nimble file resides; i.e. root dir of the package.
• binDir - Specifies the directory where nimble build will output binaries. Default: The directory in which the .nimble file resides; i.e. root dir of the packet.
• bin - A list of files which should be congenital separated by commas with no file extension required. This pick turns your bundle into a binary packet, nimble will build the files specified and install them appropriately.
• backend - Specifies the backend which will be used to build the files listed in bin. Possible values include: c, cc, cpp, objc, js. Default: c

[Deps]/[Dependencies]

Optional

• requires - Specified a list of packet names with an optional version range separated by commas. Example: nim >= 0.10.0, jester; with this value your package will depend on nim version 0.ten.0 or greater and on any version of jester.

Troubleshooting

• SSL support is not available. Cannot connect over SSL. [HttpRequestError]

Brand sure that nimble is configured to run with SSL, adding a -d:ssl flag to the file src/nimble.nim.cfg. Afterward that, you can run src/nimble install and overwrite the existing installation.

Contribution

If you would similar to help, feel complimentary to fork and brand any additions you see fit so transport a pull request.

If yous have whatsoever questions about the project yous can ask me directly on github, ask on the Nim forum, or ask on Freenode in the #nim aqueduct.

About

Nimble has been written by Dominik Picheta with help from a number of contributors. It is licensed under the BSD license (Look at license.txt for more info).

Source: https://libraries.io/nimble/nimble

Posted by: devoredist1990.blogspot.com

Share this post