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

rename Babel to Nimble

Browse source
This commit is contained in:
Pradeep Gowda 2014-11-11 10:58:53 -05:00
commit 61776c5f29
1 changed files with 40 additions and 39 deletions
Download patch file Download diff file Expand all files Collapse all files

79
developers.markdown
View file

@ -1,4 +1,4 @@
# Babel for developers # Nimble for developers
This file contains information mostly meant for developers willing to produce This file contains information mostly meant for developers willing to produce
[Nimrod](http://nimrod-lang.org) modules and submit them to the [Nimrod](http://nimrod-lang.org) modules and submit them to the
@ -7,21 +7,21 @@ user documentation is provided in the [readme.markdown file](readme.markdown).
## Packages ## Packages
A Babel package is defined by an ini-like formatted file with the ``.babel`` A Nimble package is defined by an ini-like formatted file with the ``.nimble``
extension (this document uses the term ".babel file" to refer to them). The extension (this document uses the term ".nimble file" to refer to them). The
.babel file should be named after the package it describes, i.e. a package .nimble file should be named after the package it describes, i.e. a package
named "foobar" should have a corresponding ``foobar.babel`` file. named "foobar" should have a corresponding ``foobar.nimble`` file.
These files specify information about the package including its name, author, These files specify information about the package including its name, author,
license, dependencies and more. Without one Babel is not able to install license, dependencies and more. Without one Nimble is not able to install
a package. A bare minimum .babel file follows: a package. A bare minimum .nimble file follows:
```ini ```ini
[Package] [Package]
name = "ProjectName" name = "ProjectName"
version = "0.1.0" version = "0.1.0"
author = "Your Name" author = "Your Name"
description = "Example .babel file." description = "Example .nimble file."
license = "MIT" license = "MIT"
[Deps] [Deps]
@ -31,17 +31,17 @@ Requires: "nimrod >= 0.9.2"
You may omit the dependencies entirely, but specifying the lowest version You may omit the dependencies entirely, but specifying the lowest version
of the Nimrod compiler required is recommended. of the Nimrod compiler required is recommended.
Babel 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 .babel 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.
### Libraries ### Libraries
Library packages are likely the most popular form of Babel 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 packages or the ultimate binary packages.
When babel installs a library it will copy all the files in the package When nimble installs a library it will copy all the files in the package
into ``$babelDir/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.
@ -50,7 +50,7 @@ layout is determined by the nature of your package, that is, whether your
package exposes only one module or multiple modules. package exposes 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 .babel file) of your git present in the root directory (the directory with the .nimble file) of your git
repository, it is recommended that in this case you name that module whatever repository, it is recommended that in this case you name that module whatever
your package's name is. A good example of this is the your package's name is. A good example of this is the
[jester](https://github.com/dom96/jester) package which exposes the ``jester`` [jester](https://github.com/dom96/jester) package which exposes the ``jester``
@ -68,12 +68,12 @@ them in a ``PackageName/private`` directory. Your modules may then import these
private modules with ``import PackageName/private/module``. This directory private modules with ``import PackageName/private/module``. This directory
structure may be enforced in the future. structure may be enforced in the future.
All files and folders in the directory of where the .babel file resides will be All files and folders in the directory of where the .nimble file resides will be
copied as-is, you can however skip some directories or files by setting copied as-is, you can however skip some directories or files by setting
the ``SkipDirs``, ``SkipFiles`` or ``SkipExt`` options in your .babel file. the ``SkipDirs``, ``SkipFiles`` or ``SkipExt`` options in your .nimble file.
Directories and files can also be specified on a *whitelist* basis, if you Directories and files can also be specified on a *whitelist* basis, if you
specify either of ``InstallDirs``, ``InstallFiles`` or ``InstallExt`` then specify either of ``InstallDirs``, ``InstallFiles`` or ``InstallExt`` then
Babel will **only** install the files specified. Nimble will **only** install the files specified.
### Binary packages ### Binary packages
@ -85,20 +85,20 @@ A package is automatically a binary package as soon as it sets at least one
bin = "main" bin = "main"
``` ```
In this case when ``babel install`` is invoked, babel will build the ``main.nim`` In this case when ``nimble install`` is invoked, nimble will build the ``main.nim``
file, copy it into ``$babelDir/pkgs/pkgname-ver/`` and subsequently create a file, copy it into ``$nimbleDir/pkgs/pkgname-ver/`` and subsequently create a
symlink to the binary in ``$babelDir/bin/``. On Windows a stub .bat file is symlink to the binary in ``$nimbleDir/bin/``. On Windows a stub .bat 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 you should include
``SkipExt = "nim"`` in your .babel 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. Before publishing your
package you should ensure that the dependencies you specified are correct. package you should ensure that the dependencies you specified are correct.
You can do this by running ``babel build`` or ``babel install`` in the directory You can do this by running ``nimble build`` or ``nimble install`` in the directory
of your package. of your package.
### Hybrids ### Hybrids
@ -107,11 +107,11 @@ One thing to note about library and binary package hybrids is that your binary
will most likely share the name of the package. This will mean that you will will most likely share the name of the package. This will mean that you will
not be able to put your .nim files in a ``pkgname`` directory. The current not be able to put your .nim files in a ``pkgname`` directory. The current
convention to get around this problem is to append ``pkg`` to the name as is convention to get around this problem is to append ``pkg`` to the name as is
done for babel. done for nimble.
## Dependencies ## Dependencies
Dependencies are specified under the ``[Deps]`` section in a babel file. Dependencies are specified under the ``[Deps]`` section in a nimble file.
The ``requires`` key field is used to specify them. For example: The ``requires`` key field is used to specify them. For example:
```ini ```ini
@ -128,7 +128,7 @@ 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 Babel will refuse to install the package. Similarly you should If this happens Nimble will refuse to install the package. Similarly you should
not specify an upper-bound as this can lead to a similar issue. 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.
@ -138,18 +138,18 @@ latest commit of Jester.
### Nimrod compiler ### Nimrod compiler
The Nimrod compiler cannot read .babel files. Its knowledge of Babel is The Nimrod compiler cannot read .nimble files. Its knowledge of Nimble is
limited to the ``babelPaths`` feature which allows it to use packages installed limited to the ``nimblePaths`` feature which allows it to use packages installed
in Babel's package directory when compiling your software. This means that in Nimble's package directory when compiling your software. This means that
it cannot resolve dependencies, and it can only use the latest version of a it cannot resolve dependencies, and it can only use the latest version of a
package when compiling. package when compiling.
When Babel builds your package it actually executes the Nimrod compiler. When Nimble builds your package it actually executes the Nimrod compiler.
It resolves the dependencies and feeds the path of each package to 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 babel 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
@ -158,9 +158,9 @@ 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, babel 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, babel 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, babel 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.
@ -170,11 +170,11 @@ You can force the installation of the HEAD of the repository by specifying
# Submitting your package to the package list. # Submitting your package to the package list.
Babel's packages list is stored on github and everyone is encouraged to add Nimble's packages list is stored on github and everyone is encouraged to add
their own packages to it! Take a look at their own packages to it! Take a look at
[nimrod-code/packages](https://github.com/nimrod-code/packages) to learn more. [nimrod-code/packages](https://github.com/nimrod-code/packages) to learn more.
# .babel reference # .nimble reference
## [Package] ## [Package]
@ -199,22 +199,22 @@ their own packages to it! Take a look at
* ``InstallDirs`` - A list of directories which should exclusively be installed, * ``InstallDirs`` - A list of directories which should exclusively be installed,
if this option is specified nothing else will be installed except the dirs if this option is specified nothing else will be installed except the dirs
listed here, the files listed in ``InstallFiles``, the files which share the listed here, the files listed in ``InstallFiles``, the files which share the
extensions listed in ``InstallExt``, the .babel file and the binary extensions listed in ``InstallExt``, the .nimble file and the binary
(if ``bin`` is specified). Separated by commas. (if ``bin`` is specified). Separated by commas.
* ``InstallFiles`` - A list of files which should be exclusively installed, * ``InstallFiles`` - A list of files which should be exclusively installed,
this complements ``InstallDirs`` and ``InstallExt``. Only the files listed this complements ``InstallDirs`` and ``InstallExt``. Only the files listed
here, directories listed in ``InstallDirs``, files which share the extension here, directories listed in ``InstallDirs``, files which share the extension
listed in ``InstallExt``, the .babel file and the binary (if ``bin`` is listed in ``InstallExt``, the .nimble file and the binary (if ``bin`` is
specified) will be installed. Separated by commas. specified) will be installed. Separated by commas.
* ``InstallExt`` - A list of file extensions which should be exclusively * ``InstallExt`` - A list of file extensions which should be exclusively
installed, this complements ``InstallDirs`` and ``InstallFiles``. installed, this complements ``InstallDirs`` and ``InstallFiles``.
Separated by commas. Separated by commas.
* ``srcDir`` - Specifies the directory which contains the .nim source files. * ``srcDir`` - Specifies the directory which contains the .nim source files.
**Default**: The directory in which the .babel file resides; i.e. root dir of **Default**: The directory in which the .nimble file resides; i.e. root dir of
package. 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*, babel 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``.
@ -228,3 +228,4 @@ their own packages to it! Take a look at
range separated by commas. range separated by commas.
**Example**: ``nimrod >= 0.9.2, jester``; with this value your package will **Example**: ``nimrod >= 0.9.2, jester``; with this value your package will
depend on ``nimrod`` version 0.9.2 or greater and on any version of ``jester``. depend on ``nimrod`` version 0.9.2 or greater and on any version of ``jester``.