@@ -0,0 +1,77 @@
1+.. _sect-packages:
2+
3+========
4+Packages
5+========
6+
7+``Idris`` includes a simple system for building packages from a
8+package description file. These files can be used with the ``Idris``
9+compiler to manage the development process of your ``Idris``
10+programmes and packages.
11+
12+Package Descriptions
13+--------------------
14+
15+A package description includes the following:
16+
17++ A header, consisting of the keyword package followed by the package name.
18++ Fields describing package contents, ``<field> = <value>``
19+
20+At least one field must be the modules field, where the value is a
21+comma separated list of modules. For example, a library test which
22+has two modules ``foo.idr`` and ``bar.idr`` as source files would be
23+written as follows::
24+
25+ package foo
26+
27+ modules = foo, bar
28+
29+Other examples of package files can be found in the ``libs`` directory
30+of the main ``Idris`` repository, and in `third-party libraries <https://github.com/idris-lang/Idris-dev/wiki/Libraries>`_.
31+
32+Other common fields which may be present in an ``ipkg`` file are:
33+
34++ ``sourcedir = <dir>``, which gives the directory (relative to the
35+ current directory) which contains the source. Default is the current
36+ directory.
37+
38++ ``executable = <output>``, which gives the name of the executable
39+ file to generate.
40+
41++ ``main = <module>``, which gives the name of the main module, and
42+ must be present if the executable field is present.
43+
44++ ``opts = "<idris options>"``, which allows options (such as other
45+ packages) to be passed to ``Idris``.
46+
47+In more advanced cases, particularly to support creating bindings to
48+external ``C`` libraries, the following options are available:
49+
50++ ``makefile = <file>``, which specifies a ``Makefile``, to be built
51+ before the ``Idris`` modules, for example to support linking with a
52+ ``C`` library.
53+
54++ ``libs = <libs>``, which gives a comma separated list of libraries
55+ which must be present for the package to be usable.
56+
57++ ``objs = <objs>``, which gives a comma separated list of additional
58+ object files to be installed, perhaps generated by the ``Makefile``.
59+
60+Using Package files
61+-------------------
62+
63+Given an ``Idris`` package file ``text.ipkg`` it can be used with the ``Idris`` compiler as follows:
64+
65++ ``idris --build test.ipkg`` will build all modules in the package
66+
67++ ``idris --install test.ipkg`` will install the package, making it
68+ accessible by other ``Idris`` libraries and programs.
69+
70++ ``idris --clean test.ipkg`` will delete all intermediate code and
71+ executable files generated when building.
72+
73+Once the test package has been installed, the command line option
74+``--package test`` makes it accessible (abbreviated to ``-p test``).
75+For example::
76+
77+ idris -p test Main.idr