git.iko.soy/Idris-dev
on 89c19be help sign in
Idris-dev/docs/tutorial/packages.rst
77 lines 2.6 kB history raw
1.. _sect-packages:
3********
4Packages
5********
7Idris includes a simple system for building packages from a
8package description file. These files can be used with the Idris
9compiler to manage the development process of your Idris
10programmes and packages.
12Package Descriptions
13====================
15A package description includes the following:
17+ A header, consisting of the keyword package followed by the package name.
18+ Fields describing package contents, ``<field> = <value>``
20At least one field must be the modules field, where the value is a
21comma separated list of modules. For example, a library test which
22has two modules ``foo.idr`` and ``bar.idr`` as source files would be
23written as follows::
25 package foo
27 modules = foo, bar
29Other examples of package files can be found in the ``libs`` directory
30of the main Idris repository, and in `third-party libraries <https://github.com/idris-lang/Idris-dev/wiki/Libraries>`_.
32Other common fields which may be present in an ``ipkg`` file are:
34+ ``sourcedir = <dir>``, which gives the directory (relative to the
35 current directory) which contains the source. Default is the current
36 directory.
38+ ``executable = <output>``, which gives the name of the executable
39 file to generate.
41+ ``main = <module>``, which gives the name of the main module, and
42 must be present if the executable field is present.
44+ ``opts = "<idris options>"``, which allows options (such as other
45 packages) to be passed to Idris.
47In more advanced cases, particularly to support creating bindings to
48external ``C`` libraries, the following options are available:
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.
54+ ``libs = <libs>``, which gives a comma separated list of libraries
55 which must be present for the package to be usable.
57+ ``objs = <objs>``, which gives a comma separated list of additional
58 object files to be installed, perhaps generated by the ``Makefile``.
60Using Package files
61===================
63Given an Idris package file ``text.ipkg`` it can be used with the Idris compiler as follows:
65+ ``idris --build test.ipkg`` will build all modules in the package
67+ ``idris --install test.ipkg`` will install the package, making it
68 accessible by other Idris libraries and programs.
70+ ``idris --clean test.ipkg`` will delete all intermediate code and
71 executable files generated when building.
73Once the test package has been installed, the command line option
74``--package test`` makes it accessible (abbreviated to ``-p test``).
75For example::
77 idris -p test Main.idr