git.iko.soy/Idris-dev
on 239c8ca help sign in
Idris-dev/docs/reference/packages.rst
101 lines 3.5 kB history raw
1.. _ref-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>`_.
32Common Fields
33-------------
35Other common fields which may be present in an ``ipkg`` file are:
37+ ``sourcedir = <dir>``, which takes the directory (relative to the
38 current directory) which contains the source. Default is the current
39 directory.
41+ ``executable = <output>``, which takes the name of the executable
42 file to generate.
44+ ``main = <module>``, which takes the name of the main module, and
45 must be present if the executable field is present.
47+ ``opts = "<idris options>"``, which allows options (such as other
48 packages) to be passed to Idris.
50Binding to C
51------------
53In more advanced cases, particularly to support creating bindings to
54external ``C`` libraries, the following options are available:
56+ ``makefile = <file>``, which specifies a ``Makefile``, to be built
57 before the Idris modules, for example to support linking with a
58 ``C`` library.
60+ ``libs = <libs>``, which takes a comma separated list of libraries
61 which must be present for the package to be usable.
63+ ``objs = <objs>``, which takes a comma separated list of additional
64 object files to be installed, perhaps generated by the ``Makefile``.
66Testing
67--------
69For testing Idris packages there is a rudimentary testing harness, run in the ``IO`` context.
70The ``iPKG`` file is used to specify the functions used for testing.
71The following option is available:
73+ ``tests = <test functions>``, which takes the qualified names of all test functions to be run.
75.. IMPORTANT::
76 The modules containing the test functions must also be added to the list of modules.
78Using Package files
79===================
81Given an Idris package file ``text.ipkg`` it can be used with the Idris compiler as follows:
83+ ``idris --build test.ipkg`` will build all modules in the package
85+ ``idris --install test.ipkg`` will install the package, making it
86 accessible by other Idris libraries and programs.
88+ ``idris --clean test.ipkg`` will delete all intermediate code and
89 executable files generated when building.
91+ ``idris --mkdoc test.ipkg`` will build HTML documentation for your package in the folder ``test_doc`` in your project's root directory.
93+ ``idris --checkpkg test.ipkg`` will type check all modules in the package only. This differs from build that type checks **and** generates code.
95+ ``idris --testpkg test.ipkg`` will compile and run any embedded tests you have specified in the ``tests`` paramater.
97Once the test package has been installed, the command line option
98``--package test`` makes it accessible (abbreviated to ``-p test``).
99For example::
101 idris -p test Main.idr