From d53453898e526aaeec3540d2473e8cac456657d1 Mon Sep 17 00:00:00 2001 From: Grzegorz Adam Hankiewicz Date: Sun, 24 Nov 2013 00:56:06 +0100 Subject: [PATCH] Splits main readme. Developer related information is contained in the developers.markdown file. The normal readme.markdown file now contains information about basic command line usage. --- developers.markdown | 177 +++++++++++++++++++++++++ readme.markdown | 308 ++++++++++++++++++-------------------------- 2 files changed, 300 insertions(+), 185 deletions(-) create mode 100644 developers.markdown diff --git a/developers.markdown b/developers.markdown new file mode 100644 index 0000000..9b92e0d --- /dev/null +++ b/developers.markdown @@ -0,0 +1,177 @@ +# Babel for developers + +This file contains information mostly meant for developers willing to produce +[Nimrod](http://nimrod-lang.org) modules and submit them to the +[nimrod-code/packages repository](https://github.com/nimrod-code/packages). End +user documentation is provided in the [readme.markdown file](readme.markdown). + +## Libraries + +When babel installs a library it will copy all the files that it downloaded +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. + +By convention, it is suggested that the layout be as follows. The directory +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 +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`` +module. In this case the jester package is imported with ``import jester``. + +If your package exposes multiple modules then the modules should be in a +``PackageName`` directory. This will allow for a certain measure of isolation +from other packages which expose modules with the same names. In this case +the package's modules will be imported with ``import PackageName/module``. + +You are free to combine the two approaches described. + +In regards to modules which you do **not** wish to be exposed. You should place +them in a ``PackageName/private`` directory. Your modules may then import these +private modules with ``import PackageName/private/module``. This directory +structure may be enforced in the future. + +All files and folders in the directory of where the .babel file resides will be +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. + +### 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 + +[Deps] +Requires: "nimrod >= 0.9.2" +``` + +All the fields (except ``SkipDirs`` and ``SkipFiles``) under ``[Package]`` are +required. ``[Deps]`` may be omitted. + +## 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 +``bin`` value, like so: + +```ini +bin = "main" +``` + +In this case when ``babel install`` is invoked, babel will build the ``main.nim`` +file, copy it into ``$babelDir/pkgs/pkgname-ver/`` and subsequently create a +symlink to the binary in ``$babelDir/bin/``. On Windows a stub .bat file is +created instead. + +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 +``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 + +Dependencies are specified under the ``[Deps]`` section in a babel file. +The ``requires`` key is used to specify them. For example: + +```ini +[Deps] +Requires: "nimrod >= 0.9.2, jester > 0.1 & <= 0.5" +``` + +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 (``<``), +greater-than (``>``), less-than-or-equal-to (``<=``) and greater-than-or-equal-to +(``>=``). 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. + +# Versions + +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, babel will check the +cloned repository's tags list. If no tags exist, babel will simply install the +HEAD (or tip in mercurial) of the repository. If tags exist, babel 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. + +# .babel reference + +## [Package] + +### Required + +* ``name`` - The name of the package. +* ``version`` - The *current* version of this package. This should be incremented + **after** tagging the current version using ``git tag`` or ``hg tag``. +* ``author`` - The name of the author of this package. +* ``description`` - A string describing the package. +* ``license`` - The name of the license in which this package is licensed under. + +### Optional + +* ``SkipDirs`` - A list of directory names which should be skipped during + installation, separated by commas. +* ``SkipFiles`` - A list of file names which should be skipped during + installation, separated by commas. +* ``SkipExt`` - A list of file extensions which should be skipped during + installation, the extensions should be specified without a leading ``.`` and + should be separated by commas. +* ``InstallDirs`` - A list of directories which should exclusively be installed, + 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 + extensions listed in ``InstallExt``, the .babel file and the binary + (if ``bin`` is specified). Separated by commas. +* ``InstallFiles`` - A list of files which should be exclusively installed, + this complements ``InstallDirs`` and ``InstallExt``. Only the files listed + here, directories listed in ``InstallDirs``, files which share the extension + listed in ``InstallExt``, the .babel file and the binary (if ``bin`` is + specified) will be installed. Separated by commas. +* ``InstallExt`` - A list of file extensions which should be exclusively + installed, this complements ``InstallDirs`` and ``InstallFiles``. + Separated by commas. +* ``srcDir`` - Specifies the directory which contains the .nim source files. + **Default**: The directory in which the .babel file resides; i.e. root dir of + 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*, babel 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``. + **Default**: c + +## [Deps]/[Dependencies] + +### Optional + +* ``requires`` - Specified a list of package names with an optional 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. diff --git a/readme.markdown b/readme.markdown index 8ece729..4bfb2e8 100644 --- a/readme.markdown +++ b/readme.markdown @@ -1,22 +1,125 @@ # Babel -Babel is a *beta*-grade *package manager* for the Nimrod programming language. + +Babel is a *beta*-grade *package manager* for the [Nimrod programming +language](http://nimrod-lang.org). ## Installation -You will need the latest Nimrod compiler from github to compile babel (version 0.9.2 may work). +You will need the latest [Nimrod compiler from +github](https://github.com/Araq/Nimrod) to compile babel (version 0.9.2 may +work). -Compile babel by executing: ``nimrod c -d:release babel``. Then simply install -babel by executing ``./babel install``. You should then add ``~/.babel/bin`` -to your $PATH. +Once you have the latest Nimrod compiler you can compile babel by executing: +``nimrod c -d:release babel``. Then simply install babel by executing ``./babel +install``. You should then add ``~/.babel/bin`` to your ``$PATH``. **Note**: On **Windows** you must rename ``babel.exe`` to ``babel1.exe`` and subsequently run ``babel1.exe install``. This is because Windows will lock the process which is being run. -## Babel's folder structure -Babel stores everything that has been installed in ~/.babel on Unix systems and -in your $home/.babel on Windows. Libraries are stored in $babelDir/pkgs, and -binaries are stored in $babelDir/bin. +## Babel's folder structure and packages + +Babel stores everything that has been installed in ``~/.babel`` on Unix systems +and in your ``$home/.babel`` on Windows. Libraries are stored in +``$babelDir/pkgs``, and binaries are stored in ``$babelDir/bin``. Most Babel +packages will provide ``.nim`` files and some documentation. The Nimrod +compiler is aware of Babel and will automatically find the modules so you can +``import modulename`` and have that working without additional setup. + +However, some Babel packages can provide additional tools or commands. If you +don't add their location (``$babelDir/bin``) to your ``$PATH`` they will not +work properly and you won't be able to run them. + +## Babel usage + +Once you have Babel installed on your system you can run the ``babel`` command +to obtain a list of available commands. + +### babel update + +The ``update`` command is used to fetch and update the list of Babel packages +(see below). There is no automatic update mechanism, so you need to run this +yourself if you need to *refresh* your local list of known available Babel +packages. Example: + + $ babel update + Downloading package list from https://.../packages.json + Done. + +Some commands may remind you to run ``babel update`` or will run it for you if +they fail. + +### babel install + +The ``install`` command will download and install a package. You need to pass +the name of the package (or packages) you want to install. If any of the +packages depends on other Babel packages Babel will also fetch them for you. +Example: + + $ babel install nake + Downloading nake into /tmp/babel/nake... + Executing git... + ... + nake installed successfully + +Babel always fetches and installs the latest version of a package. If you +already have that version installed it will ask to overwrite your local copy. + +If you don't specify a parameter and there is a ``package.babel`` file in your +current working directory Babel will ask if you want to install that. This can +be useful for developers who are testing locally their ``.babel`` files before +submitting them. See [developers.markdown](developers.markdown) for more info +on this. + +### babel build + +The ``build`` command is mostly used by developers who want to test building +their ``.babel`` package. The ``install`` command calls ``build`` implicitly, +so there is rarely any reason to use this command directly. + +### babel list + +The ``list`` command will display the known list of packages available for +Babel. + +### babel search + +If you don't want to go through the whole output of the ``list`` command you +can use the ``search`` command specifying as parameters the package name and/or +tags you want to filter. Babel will look into the known list of available +packages and display only those that match the specified keywords (which can be +substrings). Example: + + $ babel search math + linagl: + url: https://bitbucket.org/BitPuffin/linagl (hg) + tags: library, opengl, math, game + description: OpenGL math library + license: CC0 + + extmath: + url: git://github.com/achesak/extmath.nim (git) + tags: library, math, trigonometry + description: Nimrod math library + license: MIT + +### babel path + +The babel ``path`` command will shows the absolute path to the installed +packages matching the specified parameters. Since there can be many versions of +the same package installed, the ``path`` command will always use the latest +version. Example: + + $ babel path argument_parser + /home/user/.babel/pkgs/argument_parser-0.1.2 + +Under Unix you can use backticks to quickly access the directory of a package, +which can be useful to read the bundled documentation. Example: + + $ pwd + /usr/local/bin + $ cd `babel path argument_parser` + $ less README.md ## Packages @@ -25,186 +128,21 @@ packages is stored in a JSON file which is freely accessible in the [nimrod-code/packages repository](https://github.com/nimrod-code/packages). This JSON file provides babel with the required Git URL to clone the package and install it. Installation and build instructions are contained inside a -ini-style file with the ``.babel`` file extension. The babel file shares -the package's name. - -### Libraries - -When babel installs a library it will copy all the files that it downloaded -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. - -By convention, it is suggested that the layout be as follows. The directory -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 -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`` -module. In this case the jester package is imported with ``import jester``. - -If your package exposes multiple modules then the modules should be in a -``PackageName`` directory. This will allow for a certain measure of isolation -from other packages which expose modules with the same names. In this case -the package's modules will be imported with ``import PackageName/module``. - -You are free to combine the two approaches described. - -In regards to modules which you do **not** wish to be exposed. You should place -them in a ``PackageName/private`` directory. Your modules may then import these -private modules with ``import PackageName/private/module``. This directory -structure may be enforced in the future. - -All files and folders in the directory of where the .babel file resides will be -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. - -#### 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 - -[Deps] -Requires: "nimrod >= 0.9.2" -``` - -All the fields (except ``SkipDirs`` and ``SkipFiles``) under ``[Package]`` are -required. ``[Deps]`` may be ommitted. - -### 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 -``bin`` value, like so: - -```ini -bin = "main" -``` - -In this case when ``babel install`` is invoked, babel will build the ``main.nim`` -file, copy it into ``$babelDir/pkgs/pkgname-ver/`` and subsequently create a -symlink to the binary in ``$babelDir/bin/``. On Windows a stub .bat file is -created instead. - -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 -``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 - -Dependencies are specified under the ``[Deps]`` section in a babel file. -The ``requires`` key is used to specify them. For example: - -```ini -[Deps] -Requires: "nimrod >= 0.9.2, jester > 0.1 & <= 0.5" -``` - -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 (``<``), -greater-than (``>``), less-than-or-equal-to (``<=``) and greater-than-or-equal-to -(``>=``). 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. - -## Versions - -Versions of cloned packages via git or mercurial are determined through -the repo'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, babel -will check the cloned repo's tags list. If no tags exist, babel will simply -install the HEAD (or tip in mercurial) of the repo. If tags exist, babel 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. - -## .babel reference - -### [Package] - -#### Required - -* ``name`` - The name of the package. -* ``version`` - The *current* version of this package. This should be incremented - **after** tagging the current version using ``git tag`` or ``hg tag``. -* ``author`` - The name of the author of this package. -* ``description`` - A string describing the package. -* ``license`` - The name of the license in which this package is licensed under. - -#### Optional - -* ``SkipDirs`` - A list of directory names which should be skipped during - installation, separated by commas. -* ``SkipFiles`` - A list of file names which should be skipped during - installation, separated by commas. -* ``SkipExt`` - A list of file extensions which should be skipped during - installation, the extensions should be specified without a leading ``.`` and - should be separated by commas. -* ``InstallDirs`` - A list of directories which should exclusively be installed, - 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 - extensions listed in ``InstallExt``, the .babel file and the binary - (if ``bin`` is specified). Separated by commas. -* ``InstallFiles`` - A list of files which should be exclusively installed, - this complements ``InstallDirs`` and ``InstallExt``. Only the files listed - here, directories listed in ``InstallDirs``, files which share the extension - listed in ``InstallExt``, the .babel file and the binary (if ``bin`` is - specified) will be installed. Separated by commas. -* ``InstallExt`` - A list of file extensions which should be exclusively - installed, this complements ``InstallDirs`` and ``InstallFiles``. - Separated by commas. -* ``srcDir`` - Specifies the directory which contains the .nim source files. - **Default**: The directory in which the .babel file resides; i.e. root dir of - 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*, babel 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``. - **Default**: c - -### [Deps]/[Dependencies] - -#### Optional - -* ``requires`` - Specified a list of package names with an optional 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. +ini-style file with the ``.babel`` file extension. The babel file shares the +package's name. ## Contribution -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, + +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 are a developer willing to produce new +Babel packages please read the [developers.markdown file](developers.markdown) +for detailed information. + +If you have any questions about the project you can ask me directly on github, ask on the nimrod [forum](http://forum.nimrod-code.org), or ask on Freenode in the #nimrod channel. ## About + Babel has been written by [Dominik Picheta](http://picheta.me/) and is licensed -under the BSD license (Look at license.txt for more info). \ No newline at end of file +under the BSD license (Look at license.txt for more info).