jyapayne/nimble
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve the readme

Browse source 
- Improve grammar and spelling
- Capitalize Nimble
- Fix the link to docs/distros.html
- Switch all supporting links to HTTPS
- Link to the license file directly
This commit is contained in:
Hugo Locurcio 2017-10-04 10:45:39 +02:00
commit 7164fca394
1 changed files with 43 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

85
readme.markdown
View file

@ -1,7 +1,7 @@
# Nimble [![Build Status](https://travis-ci.org/nim-lang/nimble.svg?branch=master)](https://travis-ci.org/nim-lang/nimble) # Nimble [![Build Status](https://travis-ci.org/nim-lang/nimble.svg?branch=master)](https://travis-ci.org/nim-lang/nimble)
Nimble is a *beta*-grade *package manager* for the [Nim programming 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 Interested in learning **how to create a package**? Skip directly to that section
[here](#creating-packages). [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 Nimble has some runtime dependencies on external tools, these tools are used to
download Nimble packages. For instance, if a package is hosted on 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 installed and added to your environment ``PATH``. Same goes for
[Mercurial](http://mercurial.selenic.com) repositories on [Mercurial](http://mercurial.selenic.com) repositories on
[Bitbucket](https://bitbucket.org). Nimble packages are typically hosted in Git [Bitbucket](https://bitbucket.org). Nimble packages are typically hosted in Git
repositories so you may be able to get away without installing Mercurial. repositories so you may be able to get away without installing Mercurial.
**Warning:** Ensure that you have a fairly recent version of Git installed. **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 See [this issue](https://github.com/nim-lang/nimble/issues/105) for more
info. information.
## Installation ## 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). (since Nim version 0.15.0).
This means that you should have Nimble installed already, as long as you have 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 the latest version of Nim installed as well. Because of this **you likely do
@ -143,9 +143,9 @@ Example:
nake installed successfully nake installed successfully
Nimble always fetches and installs the latest version of a package. Note that 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 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. 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 You can force Nimble to download the latest commit from the package's repo, for
@ -153,10 +153,10 @@ example:
$ nimble install nimgame@#head $ 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``. 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: example:
$ nimble install nimgame@"> 0.5" $ 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 The ``list`` command will display the known list of packages available for
Nimble. An optional ``--ver`` parameter can be specified to tell Nimble to 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 then print the versions. Please note however that this can be slow as each
package must be queried separately. package must be queried separately.
@ -252,8 +252,8 @@ substrings). Example:
Searches are case insensitive. Searches are case insensitive.
An optional ``--ver`` parameter can be specified to tell Nimble to 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
then print the versions. Please note however that this can be slow as each then print the versions. However, please note that this can be slow as each
package must be queried separately. package must be queried separately.
### nimble path ### 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. Publishes your Nimble package to the official Nimble package repository.
**Note:** Requires a valid Github account. **Note:** Requires a valid GitHub account.
### nimble tasks ### 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 package defines. This is only supported for packages utilising the new
nimscript .nimble files. nimscript .nimble files.
@ -324,7 +324,7 @@ path = r"C:\Projects\Nim\packages.json"
You can currently configure the following in this file: 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/`` **Default:** ``~/.nimble/``
* ``chcp`` - Whether to change the current code page when executing Nim * ``chcp`` - Whether to change the current code page when executing Nim
application packages. If ``true`` this will add ``chcp 65001`` to the 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 ## 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 packages is stored in a JSON file which is freely accessible in the
[nim-lang/packages repository](https://github.com/nim-lang/packages). [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 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 package's name, i.e. a package
named "foobar" should have a corresponding ``foobar.nimble`` file. named "foobar" should have a corresponding ``foobar.nimble`` file.
These files specify information about the package including its the author, These files specify information about the package including its author,
license, dependencies and more. Without one Nimble is not able to install license, dependencies and more. Without one, Nimble is not able to install
a package. a package.
A .nimble file can be created easily using Nimble's ``init`` command. This 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 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 root of the directory or repository being installed.
The .nimble file is very flexible because it is interpreted using NimScript. 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 You can place any Nim code inside these tasks. As long as that code does not
access the FFI. The ``nimscript`` 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 additional functionality such as the ability to execute external processes
which makes this feature very powerful. 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 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 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 the root directory of the whole project. In all cases, the root directory will
contain the .nimble file. 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 The source directory can contain additional files and directories
not involved in building the project, as long as they are excluded 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: Here's a sample one-module project directory:
@ -477,7 +477,7 @@ Here's a sample one-module project directory:
├── LICENSE ├── LICENSE
├── README.md ├── README.md
├── my_project.nim # The primary source file ├── 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 └── tests # Another source directory, excluded in my_project.nimble
├── nim.cfg ├── nim.cfg
└── tests.nim └── 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 Library packages are likely the most popular form of Nimble packages. They are
meant to be used by other library or binary packages. 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 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 that the package directory layout is correct, this is so that users of the
package can correctly import the package. 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. only one module or multiple modules.
If your package exposes only a single module, then that module should be 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 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 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 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"] 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 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 symlink to the binary in ``$nimbleDir/bin/``. On Windows a stub .cmd file is
created instead. 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 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. 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. Although these have to be specific; ranges of commits are not supported.
This is done with the ``#`` character, This is done with the ``#`` character,
for example: ``jester#head``. Which will make your package depend on the 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 The ``when`` branch is important to support installation using older versions
of Nimble. 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 standard library contains a list of all the supported Operating Systems and
Linux distributions. 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. the compiler so that it knows precisely which version to use.
This means that you can safely compile using the compiler when developing your 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. to ensure that the dependencies you specified are correct.
### Versions ### 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*. repository's *tags*.
When installing a package which needs to be downloaded, after the download is 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 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 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 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 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 latest version out of the available tags, once it does so it will install the
package after checking out the latest version. 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. root dir of the package.
* ``bin`` - A list of files which should be built separated by commas with * ``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 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 * ``backend`` - Specifies the backend which will be used to build the files
listed in ``bin``. Possible values include: ``c``, ``cc``, ``cpp``, ``objc``, listed in ``bin``. Possible values include: ``c``, ``cc``, ``cpp``, ``objc``,
``js``. ``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]``` * ```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```. flag to the file ```src/nimble.nim.cfg```.
After that, you can run ```src/nimble install``` and overwrite the existing After that, you can run ```src/nimble install``` and overwrite the existing
installation. 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 If you would like to help, feel free to fork and make any additions you see fit
and then send a pull request. and then send a pull request.
If you have any questions about the project you can ask me directly on github, 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 ask on the Nim [forum](https://forum.nim-lang.org), or ask on Freenode in
the #nim channel. the #nim channel.
## Implementation details ## Implementation details
@ -877,7 +877,8 @@ the `.nimble-link` file.
## About ## 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 a number of
[contributors](https://github.com/nim-lang/nimble/graphs/contributors). [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.