Dominik Picheta
GitHub
commit
968e1a20be
1 changed files with 43 additions and 42 deletions
|
|
@ -1,7 +1,7 @@
|
|||
# Nimble [](https://travis-ci.org/nim-lang/nimble)
|
||||
|
||||
Nimble is a *beta*-grade *package manager* for the [Nim programming
|
||||
language](http://nim-lang.org).
|
||||
language](https://nim-lang.org).
|
||||
|
||||
Interested in learning **how to create a package**? Skip directly to that section
|
||||
[here](#creating-packages).
|
||||
|
|
@ -52,20 +52,20 @@ Interested in learning **how to create a package**? Skip directly to that sectio
|
|||
|
||||
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](https://github.com) you require to have [git](http://www.git-scm.com)
|
||||
[GitHub](https://github.com), you need to have [git](https://www.git-scm.com)
|
||||
installed and added to your environment ``PATH``. Same goes for
|
||||
[Mercurial](http://mercurial.selenic.com) repositories on
|
||||
[Bitbucket](https://bitbucket.org). 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.
|
||||
If the version is older than 1.9.0, then Nimble may have trouble using it.
|
||||
See [this issue](https://github.com/nim-lang/nimble/issues/105) for more
|
||||
info.
|
||||
information.
|
||||
|
||||
## Installation
|
||||
|
||||
Nimble is now bundled with [Nim](http://nim-lang.org)
|
||||
Nimble is now bundled with [Nim](https://nim-lang.org)
|
||||
(since Nim version 0.15.0).
|
||||
This means that you should have Nimble installed already, as long as you have
|
||||
the latest version of Nim installed as well. Because of this **you likely do
|
||||
|
|
@ -143,9 +143,9 @@ Example:
|
|||
nake installed successfully
|
||||
|
||||
Nimble always fetches and installs the latest version of a package. Note that
|
||||
latest version is defined as the latest tagged version in the git (or hg)
|
||||
latest version is defined as the latest tagged version in the Git (or Mercurial)
|
||||
repository, if the package has no tagged versions then the latest commit in the
|
||||
remote repository will be installed. If you already have that version installed
|
||||
remote repository will be installed. If you already have that version installed,
|
||||
Nimble will ask you whether you wish it to overwrite your local copy.
|
||||
|
||||
You can force Nimble to download the latest commit from the package's repo, for
|
||||
|
|
@ -153,10 +153,10 @@ example:
|
|||
|
||||
$ nimble install nimgame@#head
|
||||
|
||||
This is of course git specific, for hg use ``tip`` instead of ``head``. A
|
||||
This is of course Git-specific, for Mercurial, use ``tip`` instead of ``head``. A
|
||||
branch, tag, or commit hash may also be specified in the place of ``head``.
|
||||
|
||||
Instead of specifying a VCS branch you may also specify a version range, for
|
||||
Instead of specifying a VCS branch, you may also specify a version range, for
|
||||
example:
|
||||
|
||||
$ nimble install nimgame@"> 0.5"
|
||||
|
|
@ -224,7 +224,7 @@ the command ``c`` or ``compile`` is specified. The more specific ``js``, ``cc``,
|
|||
|
||||
The ``list`` command will display the known list of packages available for
|
||||
Nimble. 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
|
||||
query remote Git repositories for the list of versions of the packages and to
|
||||
then print the versions. Please note however that this can be slow as each
|
||||
package must be queried separately.
|
||||
|
||||
|
|
@ -252,8 +252,8 @@ substrings). Example:
|
|||
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 however that this can be slow as each
|
||||
query remote Git repositories for the list of versions of the packages and
|
||||
then print the versions. However, please note that this can be slow as each
|
||||
package must be queried separately.
|
||||
|
||||
### nimble path
|
||||
|
|
@ -287,11 +287,11 @@ Check out the [Creating Packages](#creating-packages) section for more info.
|
|||
|
||||
Publishes your Nimble package to the official Nimble package repository.
|
||||
|
||||
**Note:** Requires a valid Github account.
|
||||
**Note:** Requires a valid GitHub account.
|
||||
|
||||
### nimble tasks
|
||||
|
||||
For a nimble package in the current working directory, list the tasks which that
|
||||
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.
|
||||
|
||||
|
|
@ -324,7 +324,7 @@ path = r"C:\Projects\Nim\packages.json"
|
|||
|
||||
You can currently configure the following in this file:
|
||||
|
||||
* ``nimbleDir`` - The directory which nimble uses for package installation.
|
||||
* ``nimbleDir`` - The directory which Nimble uses for package installation.
|
||||
**Default:** ``~/.nimble/``
|
||||
* ``chcp`` - Whether to change the current code page when executing Nim
|
||||
application packages. If ``true`` this will add ``chcp 65001`` to the
|
||||
|
|
@ -347,17 +347,17 @@ You can currently configure the following in this file:
|
|||
|
||||
## Creating Packages
|
||||
|
||||
Nimble works on git repositories as its primary source of packages. Its list of
|
||||
Nimble works on Git repositories as its primary source of packages. Its list of
|
||||
packages is stored in a JSON file which is freely accessible in the
|
||||
[nim-lang/packages repository](https://github.com/nim-lang/packages).
|
||||
This JSON file provides nimble with the required Git URL to clone the package
|
||||
This JSON file provides Nimble with the required Git URL to clone the package
|
||||
and install it. Installation and build instructions are contained inside a
|
||||
file with the ``.nimble`` file extension. The nimble file shares the
|
||||
file with the ``.nimble`` file extension. The Nimble file shares the
|
||||
package's name, i.e. a package
|
||||
named "foobar" should have a corresponding ``foobar.nimble`` file.
|
||||
|
||||
These files specify information about the package including its the author,
|
||||
license, dependencies and more. Without one Nimble is not able to install
|
||||
These files specify information about the package including its author,
|
||||
license, dependencies and more. Without one, Nimble is not able to install
|
||||
a package.
|
||||
|
||||
A .nimble file can be created easily using Nimble's ``init`` command. This
|
||||
|
|
@ -392,7 +392,7 @@ requires "fizzbuzz >= 1.0"
|
|||
```
|
||||
|
||||
Nimble currently supports installation of packages from a local directory, a
|
||||
git repository and a mercurial repository. The .nimble file must be present in
|
||||
Git repository and a mercurial repository. The .nimble file must be present in
|
||||
the root of the directory or repository being installed.
|
||||
|
||||
The .nimble file is very flexible because it is interpreted using NimScript.
|
||||
|
|
@ -420,7 +420,7 @@ Hello World!
|
|||
|
||||
You can place any Nim code inside these tasks. As long as that code does not
|
||||
access the FFI. The ``nimscript``
|
||||
[module](http://nim-lang.org/docs/nimscript.html) in Nim's standard library defines
|
||||
[module](https://nim-lang.org/docs/nimscript.html) in Nim's standard library defines
|
||||
additional functionality such as the ability to execute external processes
|
||||
which makes this feature very powerful.
|
||||
|
||||
|
|
@ -457,7 +457,7 @@ which are also useful. Take a look at it for more information.
|
|||
|
||||
A Nimble project includes a *source directory*, containing at most one
|
||||
primary source file, which shares the same name as the project itself (as well
|
||||
as the project's nimble file). In most cases this source directory will also be
|
||||
as the project's .nimble file). In most cases this source directory will also be
|
||||
the root directory of the whole project. In all cases, the root directory will
|
||||
contain the .nimble file.
|
||||
|
||||
|
|
@ -468,7 +468,7 @@ will have the same name as the project (see below for details).
|
|||
|
||||
The source directory can contain additional files and directories
|
||||
not involved in building the project, as long as they are excluded
|
||||
in the nimble file.
|
||||
in the .nimble file.
|
||||
|
||||
Here's a sample one-module project directory:
|
||||
|
||||
|
|
@ -477,7 +477,7 @@ Here's a sample one-module project directory:
|
|||
├── LICENSE
|
||||
├── README.md
|
||||
├── my_project.nim # The primary source file
|
||||
├── my_project.nimble # The project nimble file
|
||||
├── my_project.nimble # The project .nimble file
|
||||
└── tests # Another source directory, excluded in my_project.nimble
|
||||
├── nim.cfg
|
||||
└── tests.nim
|
||||
|
|
@ -518,7 +518,7 @@ You can compile and run a single tester application or multiple test files.
|
|||
Library packages are likely the most popular form of Nimble packages. They are
|
||||
meant to be used by other library or binary packages.
|
||||
|
||||
When nimble installs a library it will copy all of its files
|
||||
When Nimble installs a library, it will copy all of its files
|
||||
into ``$nimbleDir/pkgs/pkgname-ver``. It's up to the package creator to make sure
|
||||
that the package directory layout is correct, this is so that users of the
|
||||
package can correctly import the package.
|
||||
|
|
@ -528,7 +528,7 @@ determined by the nature of your package, that is, whether your package exposes
|
|||
only one module or multiple modules.
|
||||
|
||||
If your package exposes only a single module, then that module should be
|
||||
present in the root directory (the directory with the .nimble file) of your git
|
||||
present in the root directory (the directory with the .nimble file) of your Git
|
||||
repository, and should be named whatever your package's name is. A good example
|
||||
of this is the [jester](https://github.com/dom96/jester) package which exposes
|
||||
the ``jester`` module. In this case the jester package is imported with
|
||||
|
|
@ -571,7 +571,7 @@ A package is automatically a binary package as soon as it sets at least one
|
|||
bin = @["main"]
|
||||
```
|
||||
|
||||
In this case when ``nimble install`` is invoked, nimble will build the ``main.nim``
|
||||
In this case when ``nimble install`` is invoked, Nimble will build the ``main.nim``
|
||||
file, copy it into ``$nimbleDir/pkgs/pkgname-ver/`` and subsequently create a
|
||||
symlink to the binary in ``$nimbleDir/bin/``. On Windows a stub .cmd file is
|
||||
created instead.
|
||||
|
|
@ -621,9 +621,9 @@ and less than 1.0.
|
|||
|
||||
Specifying a concrete version as a dependency is not a good idea because your
|
||||
package may end up depending on two different versions of the same package.
|
||||
If this happens Nimble will refuse to install the package.
|
||||
If this happens, Nimble will refuse to install the package.
|
||||
|
||||
In addition to versions you may also specify git/hg tags, branches and commits.
|
||||
In addition to versions you may also specify Git/Mercurial tags, branches and commits.
|
||||
Although these have to be specific; ranges of commits are not supported.
|
||||
This is done with the ``#`` character,
|
||||
for example: ``jester#head``. Which will make your package depend on the
|
||||
|
|
@ -654,7 +654,7 @@ when defined(nimdistros):
|
|||
The ``when`` branch is important to support installation using older versions
|
||||
of Nimble.
|
||||
|
||||
The [distros module](nim-lang.org/docs/distros.html) in Nim's
|
||||
The [distros module](https://nim-lang.org/docs/distros.html) in Nim's
|
||||
standard library contains a list of all the supported Operating Systems and
|
||||
Linux distributions.
|
||||
|
||||
|
|
@ -680,18 +680,18 @@ It 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 can safely compile using the compiler when developing your
|
||||
software, but you should use nimble to build the package before publishing it
|
||||
software, but you should use Nimble to build the package before publishing it
|
||||
to ensure that the dependencies you specified are correct.
|
||||
|
||||
### Versions
|
||||
|
||||
Versions of cloned packages via git or mercurial are determined through the
|
||||
Versions of cloned packages via Git or Mercurial are determined through the
|
||||
repository's *tags*.
|
||||
|
||||
When installing a package which needs to be downloaded, after the download is
|
||||
complete and if the package is distributed through a VCS, nimble will 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 exist, nimble will attempt
|
||||
complete and if the package is distributed through a VCS, Nimble will 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 exist, Nimble will attempt
|
||||
to look for tags which resemble versions (e.g. v0.1) and will then find the
|
||||
latest version out of the available tags, once it does so it will install the
|
||||
package after checking out the latest version.
|
||||
|
|
@ -781,7 +781,7 @@ Nimble includes a ``publish`` command which does this for you automatically.
|
|||
root dir of the package.
|
||||
* ``bin`` - A list of files which should be built separated by commas with
|
||||
no file extension required. This option turns your package into a *binary
|
||||
package*, nimble will build the files specified and install them appropriately.
|
||||
package*, 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``.
|
||||
|
|
@ -813,7 +813,7 @@ work properly and you won't be able to run them.
|
|||
|
||||
* ```SSL support is not available. Cannot connect over SSL. [HttpRequestError]```
|
||||
|
||||
Make sure that nimble is configured to run with SSL, adding a ```-d:ssl```
|
||||
Make sure that Nimble is configured to run with SSL, adding a ```-d:ssl```
|
||||
flag to the file ```src/nimble.nim.cfg```.
|
||||
After that, you can run ```src/nimble install``` and overwrite the existing
|
||||
installation.
|
||||
|
|
@ -855,8 +855,8 @@ A new Nim release (via ``koch xz``) will always bundle the ``stable`` branch.
|
|||
If you would like to help, feel free to fork and make any additions you see fit
|
||||
and then send a pull request.
|
||||
|
||||
If you have any questions about the project you can ask me directly on github,
|
||||
ask on the Nim [forum](http://forum.nim-lang.org), or ask on Freenode in
|
||||
If you have any questions about the project, you can ask me directly on GitHub,
|
||||
ask on the Nim [forum](https://forum.nim-lang.org), or ask on Freenode in
|
||||
the #nim channel.
|
||||
|
||||
## Implementation details
|
||||
|
|
@ -877,7 +877,8 @@ the `.nimble-link` file.
|
|||
|
||||
## About
|
||||
|
||||
Nimble has been written by [Dominik Picheta](http://picheta.me/) with help from
|
||||
Nimble has been written by [Dominik Picheta](https://picheta.me/) with help from
|
||||
a number of
|
||||
[contributors](https://github.com/nim-lang/nimble/graphs/contributors).
|
||||
It is licensed under the BSD license (Look at license.txt for more info).
|
||||
It is licensed under the 3-clause BSD license, see [license.txt](license.txt)
|
||||
for more information.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue