From 7164fca394151e60b60a60216f6bf56c5ba23d2e Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Wed, 4 Oct 2017 10:45:39 +0200 Subject: [PATCH] Improve the readme - 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 --- readme.markdown | 85 +++++++++++++++++++++++++------------------------ 1 file changed, 43 insertions(+), 42 deletions(-) diff --git a/readme.markdown b/readme.markdown index 31bf262..b479d77 100644 --- a/readme.markdown +++ b/readme.markdown @@ -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 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 [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 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 [Mercurial](http://mercurial.selenic.com) repositories on [Bitbucket](https://bitbucket.org). Nimble packages are typically hosted in Git repositories so you may be able to get away without installing Mercurial. **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 -info. +information. ## 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). 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 @@ -143,9 +143,9 @@ Example: nake installed successfully 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 -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. You can force Nimble to download the latest commit from the package's repo, for @@ -153,10 +153,10 @@ example: $ 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``. -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: $ 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 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 package must be queried separately. @@ -252,8 +252,8 @@ substrings). Example: Searches are case insensitive. 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 -then print the versions. Please note however that this can be slow as each +query remote Git repositories for the list of versions of the packages and +then print the versions. However, please note that this can be slow as each package must be queried separately. ### 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. -**Note:** Requires a valid Github account. +**Note:** Requires a valid GitHub account. ### 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 nimscript .nimble files. @@ -324,7 +324,7 @@ path = r"C:\Projects\Nim\packages.json" 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/`` * ``chcp`` - Whether to change the current code page when executing Nim 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 -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 [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 -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 named "foobar" should have a corresponding ``foobar.nimble`` file. -These files specify information about the package including its the author, -license, dependencies and more. Without one Nimble is not able to install +These files specify information about the package including its author, +license, dependencies and more. Without one, Nimble is not able to install a package. 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 -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 .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 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 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 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 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 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: @@ -477,7 +477,7 @@ Here's a sample one-module project directory: ├── LICENSE ├── README.md ├── 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 ├── nim.cfg └── 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 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 that the package directory layout is correct, this is so that users of the 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. 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 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 @@ -571,7 +571,7 @@ A package is automatically a binary package as soon as it sets at least one 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 symlink to the binary in ``$nimbleDir/bin/``. On Windows a stub .cmd file is 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 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. This is done with the ``#`` character, 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 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 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. 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. ### 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*. 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 -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 +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 +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 latest version out of the available tags, once it does so it will install the 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. * ``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*, 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 listed in ``bin``. Possible values include: ``c``, ``cc``, ``cpp``, ``objc``, ``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]``` -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```. After that, you can run ```src/nimble install``` and overwrite the existing 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 and then send a pull request. -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 +If you have any questions about the project, you can ask me directly on GitHub, +ask on the Nim [forum](https://forum.nim-lang.org), or ask on Freenode in the #nim channel. ## Implementation details @@ -877,7 +877,8 @@ the `.nimble-link` file. ## 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 [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.