Nim/doc/niminst.rst

=========================
  niminst User's manual
=========================

:Author: Andreas Rumpf
:Version: |nimversion|

.. contents::

Introduction
============

niminst is a tool to generate an installer for a Nim program. Currently
it can create an installer for Windows
via `Inno Setup <http://www.jrsoftware.org/isinfo.php>`_ as well as
installation/deinstallation scripts for UNIX. Later versions will support
Linux' package management systems.

niminst works by reading a configuration file that contains all the
information that it needs to generate an installer for the different operating
systems.


Configuration file
==================

niminst uses the Nim `parsecfg <parsecfg.html>`_ module to parse the
configuration file. Here's an example of how the syntax looks like:

.. include:: mytest.cfg
     :literal:

The value of a key-value pair can reference user-defined variables via
the ``$variable`` notation: They can be defined in the command line with the
``--var:name=value`` switch. This is useful to not hard-coding the
program's version number into the configuration file, for instance.

It follows a description of each possible section and how it affects the
generated installers.


Project section
---------------
The project section gathers general information about your project. It must
contain the following key-value pairs:

====================   =======================================================
Key                    description
====================   =======================================================
``Name``               the project's name; this needs to be a single word
``DisplayName``        the project's long name; this can contain spaces. If
                       not specified, this is the same as ``Name``.
``Version``            the project's version
``OS``                 the OSes to generate C code for; for example:
                       ``"windows;linux;macosx"``
``CPU``                the CPUs to generate C code for; for example:
                       ``"i386;amd64;powerpc"``
``Authors``            the project's authors
``Description``        the project's description
``App``                the application's type: "Console" or "GUI". If
                       "Console", niminst generates a special batch file
                       for Windows to open up the command-line shell.
``License``            the filename of the application's license
====================   =======================================================


``files`` key
-------------

Many sections support the ``files`` key. Listed filenames
can be separated by semicolon or the ``files`` key can be repeated. Wildcards
in filenames are supported. If it is a directory name, all files in the
directory are used::

  [Config]
  Files: "configDir"
  Files: "otherconfig/*.conf;otherconfig/*.cfg"


Config section
--------------

The ``config`` section currently only supports the ``files`` key. Listed files
will be installed into the OS's configuration directory.


Documentation section
---------------------

The ``documentation`` section supports the ``files`` key.
Listed files will be installed into the OS's native documentation directory
(which might be ``$appdir/doc``).

There is a ``start`` key which determines whether the Windows installer
generates a link to e.g. the ``index.html`` of your documentation.


Other section
-------------

The ``other`` section currently only supports the ``files`` key.
Listed files will be installed into the application installation directory
(``$appdir``).


Lib section
-----------

The ``lib`` section currently only supports the ``files`` key.
Listed files will be installed into the OS's native library directory
(which might be ``$appdir/lib``).


Windows section
---------------

The ``windows`` section supports the ``files`` key for Windows-specific files.
Listed files will be installed into the application installation directory
(``$appdir``).

Other possible options are:

====================   =======================================================
Key                    description
====================   =======================================================
``BinPath``            paths to add to the Windows ``%PATH%`` environment
                       variable. Example: ``BinPath: r"bin;dist\mingw\bin"``
``InnoSetup``          boolean flag whether an Inno Setup installer should be
                       generated for Windows. Example: ``InnoSetup: "Yes"``
====================   =======================================================


UnixBin section
---------------

The ``UnixBin`` section currently only supports the ``files`` key.
Listed files will be installed into the OS's native bin directory
(e.g. ``/usr/local/bin``). The exact location depends on the
installation path the user specifies when running the ``install.sh`` script.


Unix section
------------

Possible options are:

====================   =======================================================
Key                    description
====================   =======================================================
``InstallScript``      boolean flag whether an installation shell script
                       should be generated. Example: ``InstallScript: "Yes"``
``UninstallScript``    boolean flag whether a de-installation shell script
                       should be generated.
                       Example: ``UninstallScript: "Yes"``
====================   =======================================================


InnoSetup section
-----------------

Possible options are:

====================   =======================================================
Key                    description
====================   =======================================================
``path``               Path to Inno Setup.
                       Example: ``path = r"c:\inno setup 5\iscc.exe"``
``flags``              Flags to pass to Inno Setup.
                       Example: ``flags = "/Q"``
====================   =======================================================


C_Compiler section
------------------

Possible options are:

====================   =======================================================
Key                    description
====================   =======================================================
``path``               Path to the C compiler.
``flags``              Flags to pass to the C Compiler.
                       Example: ``flags = "-w"``
====================   =======================================================


Real-world example
==================

The installers for the Nim compiler itself are generated by niminst. Have a
look at its configuration file:

.. include:: ../compiler/installer.ini
     :literal: