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

Many additions/improvements to readme. Fixes #221. Fixes #246.

Browse source
This commit is contained in:
Dominik Picheta 2016-12-23 12:42:08 +01:00
commit 8d51fc4c2f
1 changed files with 128 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

177
readme.markdown
View file

@ -12,33 +12,36 @@ Interested in learning **how to create a package**? Skip directly to that sectio
- [Installation](#installation) - [Installation](#installation)
- [Nimble's folder structure and packages](#nimbles-folder-structure-and-packages) - [Nimble's folder structure and packages](#nimbles-folder-structure-and-packages)
- [Nimble usage](#nimble-usage) - [Nimble usage](#nimble-usage)
- [nimble refresh](#nimble-refresh) - [nimble refresh](#nimble-refresh)
- [nimble install](#nimble-install) - [nimble install](#nimble-install)
- [nimble uninstall](#nimble-uninstall) - [nimble uninstall](#nimble-uninstall)
- [nimble build](#nimble-build) - [nimble build](#nimble-build)
- [nimble c](#nimble-c) - [nimble c](#nimble-c)
- [nimble list](#nimble-list) - [nimble list](#nimble-list)
- [nimble search](#nimble-search) - [nimble search](#nimble-search)
- [nimble path](#nimble-path) - [nimble path](#nimble-path)
- [nimble init](#nimble-init) - [nimble init](#nimble-init)
- [nimble publish](#nimble-publish) - [nimble publish](#nimble-publish)
- [nimble tasks](#nimble-tasks) - [nimble tasks](#nimble-tasks)
- [nimble dump](#nimble-dump) - [nimble dump](#nimble-dump)
- [Configuration](#configuration) - [Configuration](#configuration)
- [Creating Packages](#creating-packages) - [Creating Packages](#creating-packages)
- [Libraries](#libraries) - [Project structure](#project-structure)
- [Binary packages](#binary-packages) - [Tests](#tests)
- [Hybrids](#hybrids) - [Libraries](#libraries)
- [Dependencies](#dependencies) - [Binary packages](#binary-packages)
- [Nim compiler](#nim-compiler) - [Hybrids](#hybrids)
- [Versions](#versions) - [Dependencies](#dependencies)
- [Submitting your package to the package list.](#submitting-your-package-to-the-package-list) - [Nim compiler](#nim-compiler)
- [Versions](#versions)
- [Releasing a new version](#releasing-a-new-version)
- [Publishing packages](#publishing-packages)
- [.nimble reference](#nimble-reference) - [.nimble reference](#nimble-reference)
- [[Package]](#package) - [[Package]](#package)
- [Required](#required) - [Required](#required)
- [Optional](#optional) - [Optional](#optional)
- [[Deps]/[Dependencies]](#depsdependencies) - [[Deps]/[Dependencies]](#depsdependencies)
- [Optional](#optional) - [Optional](#optional)
- [Troubleshooting](#troubleshooting) - [Troubleshooting](#troubleshooting)
- [Contribution](#contribution) - [Contribution](#contribution)
- [About](#about) - [About](#about)
@ -194,9 +197,10 @@ Similar to the ``install`` command you can specify a version range, for example:
### nimble build ### nimble build
The ``build`` command is mostly used by developers who want to test building The ``build`` command is mostly used by developers who want to test building
their ``.nimble`` package. This command will build the package in debug mode, their ``.nimble`` package. This command will build the package with default
without installing anything. The ``install`` command will build the package flags, i.e. a debug build which includes stack traces but no GDB debug
in release mode instead. information.
The ``install`` command will build the package in release mode instead.
### nimble c ### nimble c
@ -372,6 +376,7 @@ You can also specify multiple dependencies like so:
requires "nim >= 0.10.0", "foobar >= 0.1.0" requires "nim >= 0.10.0", "foobar >= 0.1.0"
requires "fizzbuzz >= 1.0" 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
@ -435,12 +440,54 @@ also return ``false`` from these blocks to stop further execution.
The ``nimscriptapi.nim`` module specifies this and includes other definitions The ``nimscriptapi.nim`` module specifies this and includes other definitions
which are also useful. Take a look at it for more information. which are also useful. Take a look at it for more information.
### Project structure
There is nothing surprising about the recommended project structure. The advice
resembles that of many other package managers.
| Directory | Purpose |
| ------------- | -------------------------------------- |
| ``.`` | Root directory containing .nimble file.|
| ``./src/`` | Project source code |
| ``./tests/`` | Project test files |
| ``./docs/`` | Project documentation |
#### Tests
A common problem that arises with tests is the fact that they need to import
the associated package. But the package is in the parent directory. This can
be solved in a few different ways:
* Expect that the package has been installed locally into your
``~/.nimble`` directory.
* Use a simple path modification to resolve the package properly.
The latter is highly recommended. Reinstalling the package to test an actively
changing code base is a massive pain.
To modify the path for your tests only, simply add a ``nim.cfg`` file into
your ``tests`` directory with the following contents:
```
--path:"../src/"
```
To make testing even more convenient, you may wish to define a ``test`` task
in your ``.nimble`` file. Like so:
```nim
task "test", "Runs the test suite":
exec "nim c -r tests/tester"
```
You can compile and run a single tester application or multiple test files.
### Libraries ### Libraries
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 packages or the ultimate binary packages. meant to be used by other library or binary packages.
When nimble installs a library it will copy all the files in the package 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.
@ -482,23 +529,23 @@ A package is automatically a binary package as soon as it sets at least one
``bin`` value, like so: ``bin`` value, like so:
```ini ```ini
bin = "main" # NimScript config expects a seq instead, e.g. @["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 .bat file is symlink to the binary in ``$nimbleDir/bin/``. On Windows a stub .cmd file is
created instead. created instead.
Other files will be copied in the same way as they are for library packages. Other files will be copied in the same way as they are for library packages.
Binary packages should not install .nim files so you should include Binary packages should not install .nim files so include
``SkipExt = "nim"`` in your .nimble file, unless you intend for your package to ``SkipExt = "nim"`` in your .nimble file, unless you intend for your package to
be a binary/library combo which is fine. be a binary/library combo which is fine.
Dependencies are automatically installed before building. Before publishing your Dependencies are automatically installed before building.
package you should ensure that the dependencies you specified are correct. It's a good idea to test that the dependencies you specified are correct by
You can do this by running ``nimble build`` or ``nimble install`` in the directory running by running ``nimble build`` or ``nimble install`` in the directory
of your package. of your package.
### Hybrids ### Hybrids
@ -515,28 +562,28 @@ done for nimble.
### Dependencies ### Dependencies
Dependencies are specified under the ``[Deps]`` section in a nimble file. Dependencies are specified using the ``requires`` function. For example:
The ``requires`` key field is used to specify them. For example:
```ini ```
[Deps] # Dependencies
Requires: "nim >= 0.10.0, jester > 0.1 & <= 0.5" requires "nim >= 0.10.0", "jester > 0.1 & <= 0.5"
``` ```
Dependency lists support version ranges. These versions may either be a concrete Dependency lists support version ranges. These versions may either be a concrete
version like ``0.1``, or they may contain any of the less-than (``<``), version like ``0.1``, or they may contain any of the less-than (``<``),
greater-than (``>``), less-than-or-equal-to (``<=``) and greater-than-or-equal-to greater-than (``>``), less-than-or-equal-to (``<=``) and greater-than-or-equal-to
(``>=``). Two version ranges may be combined using the ``&`` operator for example: (``>=``) oeprators.
``> 0.2 & < 1.0`` which will install a package with the version greater than 0.2 Two version ranges may be combined using the ``&`` operator, for example
``> 0.2 & < 1.0``, which will install a package with the version greater than 0.2
and less than 1.0. 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. Similarly you should If this happens Nimble will refuse to install the package.
not specify an upper-bound as this can lead to a similar issue.
In addition to versions you may also specify git/hg tags, branches and commits. In addition to versions you may also specify git/hg tags, branches and commits.
These have to be concrete however. This is done with the ``#`` character, 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 for example: ``jester#head``. Which will make your package depend on the
latest commit of Jester. latest commit of Jester.
@ -572,11 +619,43 @@ package after checking out the latest version.
You can force the installation of the HEAD of the repository by specifying You can force the installation of the HEAD of the repository by specifying
``#head`` after the package name in your dependency list. ``#head`` after the package name in your dependency list.
## Submitting your package to the package list. #### Releasing a new version
Nimble's packages list is stored on github and everyone is encouraged to add Version releases are done by creating a tag in your Git or Mercurial
their own packages to it! Take a look at repository.
[nim-lang/packages](https://github.com/nim-lang/packages) to learn more.
Whenever you want to release a new version, you should remember to first
increment the version in your ``.nimble`` file and commit your changes. Only
after that is done should you tag the release.
To summarise, the steps for release are:
* Increment the version in your ``.nimble`` file.
* Commit your changes.
* Tag your release, by for example running ``git tag v0.2.0``.
* Push your tags and commits.
Once the new tag is in the remote repository, Nimble will be able to detect
the new version.
##<a name="submitting-your-package-to-the-package-list"> Publishing packages
Publishing packages isn't a requirement. But doing so allows people to associate
a specific name to a URL pointing to your package. This mapping is stored
in an official packages repository located
[here](https://github.com/nim-lang/packages).
This repository contains a ``packages.json`` file which lists all the published
packages. It contains a set of package names with associated metadata. You
can read more about this metadata in the
[readme for the packages repository](https://github.com/nim-lang/packages#readme).
To publish your package you need to fork that repository, and add an entry
into the ``packages.json`` file for your package. Then create a pull request
with your changes. **You only need to do this
once**.
Nimble includes a ``publish`` command which does this for you automatically.
## .nimble reference ## .nimble reference