diff options
Diffstat (limited to 'doc/niminst.rst')
| -rw-r--r-- | doc/niminst.rst | 195 |
1 files changed, 195 insertions, 0 deletions
diff --git a/doc/niminst.rst b/doc/niminst.rst new file mode 100644 index 000000000..bf5cb0f50 --- /dev/null +++ b/doc/niminst.rst @@ -0,0 +1,195 @@ +========================= + 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 deinstallation 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: + |