From 99ae796dabd59a4e3a011aa4557637817bef2ea4 Mon Sep 17 00:00:00 2001 From: Dominik Picheta Date: Tue, 24 Jun 2014 00:15:26 +0100 Subject: [PATCH] Updated developers docs. --- developers.markdown | 122 +++++++++++++++++++++++++++++--------------- 1 file changed, 81 insertions(+), 41 deletions(-) diff --git a/developers.markdown b/developers.markdown index c2ca5f4..e170c04 100644 --- a/developers.markdown +++ b/developers.markdown @@ -5,9 +5,42 @@ This file contains information mostly meant for developers willing to produce [nimrod-code/packages repository](https://github.com/nimrod-code/packages). End user documentation is provided in the [readme.markdown file](readme.markdown). -## Libraries +## Packages -When babel installs a library it will copy all the files that it downloaded +A Babel package is defined by an ini-like formatted file with the ``.babel`` +extension (this document uses the term ".babel file" to refer to them). The +.babel file should be named after the package it describes, i.e. a package +named "foobar" should have a corresponding ``foobar.babel`` file. + +These files specify information about the package including its name, author, +license, dependencies and more. Without one Babel is not able to install +a package. A bare minimum .babel file follows: + +```ini +[Package] +name = "ProjectName" +version = "0.1.0" +author = "Your Name" +description = "Example .babel file." +license = "MIT" + +[Deps] +Requires: "nimrod >= 0.9.2" +``` + +You may omit the dependencies entirely, but specifying the lowest version +of the Nimrod compiler required is recommended. + +Babel currently supports installation of packages from a local directory, a +git repository and a mercurial repository. The .babel file must be present in +the root of the directory or repository being installed. + +### Libraries + +Library packages are likely the most popular form of Babel packages. They are +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 into ``$babelDir/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. @@ -17,7 +50,7 @@ layout is 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 babel file) of your git +present in the root directory (the directory with the .babel file) of your git 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 [jester](https://github.com/dom96/jester) package which exposes the ``jester`` @@ -40,34 +73,9 @@ copied as-is, you can however skip some directories or files by setting the ``SkipDirs``, ``SkipFiles`` or ``SkipExt`` options in your .babel file. Directories and files can also be specified on a *whitelist* basis, if you specify either of ``InstallDirs``, ``InstallFiles`` or ``InstallExt`` then -babel will **only** install the files specified. +Babel will **only** install the files specified. -### Example library .babel file - -```ini -[Package] -name = "ProjectName" -version = "0.1.0" -author = "Your Name" -description = "Example .babel file." -license = "MIT" - -SkipDirs = "SomeDir" ; ./SomeDir will not be installed -SkipFiles = "file.txt,file2.txt" ; ./{file.txt, file2.txt} will not be installed -SkipFiles = """ - foo.txt - foo2.rst - foo3.md -""" ; Listing the files on multiple lines also works. - -[Deps] -Requires: "nimrod >= 0.9.2" -``` - -All the fields (except ``SkipDirs`` and ``SkipFiles``) under ``[Package]`` are -required. ``[Deps]`` may be omitted. - -## Binary packages +### Binary packages These are application packages which require building prior to installation. A package is automatically a binary package as soon as it sets at least one @@ -88,9 +96,12 @@ Binary packages should not install .nim files so you should include ``SkipExt = "nim"`` in your .babel file, unless you intend for your package to be a binary/library combo which is fine. -Dependencies are automatically installed before building. +Dependencies are automatically installed before building. Before publishing your +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 +of your package. -## Hybrids +### Hybrids 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 @@ -98,10 +109,10 @@ 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 done for babel. -# Dependencies +## Dependencies Dependencies are specified under the ``[Deps]`` section in a babel file. -The ``requires`` key is used to specify them. For example: +The ``requires`` key field is used to specify them. For example: ```ini [Deps] @@ -115,7 +126,33 @@ greater-than (``>``), less-than-or-equal-to (``<=``) and greater-than-or-equal-t ``> 0.2 & < 1.0`` which will install a package with the version greater than 0.2 and less than 1.0. -# Versions +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 Babel will refuse to install the package. Similarly you should +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. +These have to be concrete however. This is done with the ``#`` character, +for example: ``jester#head``. Which will make your package depend on the +latest commit of Jester. + +### Nimrod compiler + +The Nimrod compiler cannot read .babel files. Its knowledge of Babel is +limited to the ``babelPaths`` feature which allows it to use packages installed +in Babel's package directory when compiling your software. This means that +it cannot resolve dependencies, and it can only use the latest version of a +package when compiling. + +When Babel builds your package it actually executes the Nimrod compiler. +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 babel 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 repository's *tags*. @@ -128,6 +165,15 @@ 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. +You can force the installation of the HEAD of the repository by specifying +``#head`` after the package name in your dependency list. + +# Submitting your package to the package list. + +Babel's packages list is stored on github and everyone is encouraged to add +their own packages to it! Take a look at +[nimrod-code/packages](https://github.com/nimrod-code/packages) to learn more. + # .babel reference ## [Package] @@ -182,9 +228,3 @@ package after checking out the latest version. range separated by commas. **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``. - -# Submitting your package to the package list. - -Babel's packages list is stored on github and everyone is encouraged to add -their own packages to it! Take a look at -[nimrod-code/packages](https://github.com/nimrod-code/packages) to learn more.