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.
15A package description includes the following:
17+ A header, consisting of the keyword package followed by the package
18 name. Package names can be any valid Idris identifier. The iPKG
19 format also takes a quoted version that accepts any valid filename.
20+ Fields describing package contents, ``<field> = <value>``
22At least one field must be the modules field, where the value is a
23comma separated list of modules. For example, a library test which
24has two modules ``foo.idr`` and ``bar.idr`` as source files would be
31Other examples of package files can be found in the ``libs`` directory
32of the main Idris repository, and in `third-party libraries <https://github.com/idris-lang/Idris-dev/wiki/Libraries>`_.
37From Idris `v0.12` the `iPKG` format supports additional metadata
38associated with the package.
41+ ``brief = "<text>"``, a string literal containing a brief description
44+ ``version = <text>``, a version string to associate with the package.
46+ ``readme = <file>``, location of the README file.
48+ ``license = <text>``, a string description of the licensing
51+ ``author = <text>``, the author information.
53+ ``maintainer = <text>``, Maintainer information.
55+ ``homepage = <url>``, the website associated with the package.
57+ ``sourceloc = <url>``, the location of the DVCS where the source
60+ ``bugtracker = <url>``, the location of the project's bug tracker.
66Other common fields which may be present in an ``ipkg`` file are:
68+ ``sourcedir = <dir>``, which takes the directory (relative to the
69 current directory) which contains the source. Default is the current
72+ ``executable = <output>``, which takes the name of the executable
73 file to generate. Executable names can be any valid Idris
74 identifier. the iPKG format also takes a quoted version that accepts
77+ ``main = <module>``, which takes the name of the main module, and
78 must be present if the executable field is present.
80+ ``opts = "<idris options>"``, which allows options to be passed to
83+ ``pkgs = <pkg name> (',' <pkg name>)+``, a comma separated list of
84 package names that the Idris package requires.
89In more advanced cases, particularly to support creating bindings to
90external ``C`` libraries, the following options are available:
92+ ``makefile = <file>``, which specifies a ``Makefile``, to be built
93 before the Idris modules, for example to support linking with a
94 ``C`` library. When building, Idris sets the environment variables
95 ``IDRIS_INCLUDES`` (with C include flags) and ``IDRIS_LDFLAGS``
96 (with C linking flags) so they can be used from inside the
99+ ``libs = <libs>``, which takes a comma separated list of libraries
100 which must be present for the package to be usable.
102+ ``objs = <objs>``, which takes a comma separated list of additional
103 files to be installed (object files, headers), perhaps generated
109For testing Idris packages there is a rudimentary testing harness, run in the ``IO`` context.
110The ``iPKG`` file is used to specify the functions used for testing.
111The following option is available:
113+ ``tests = <test functions>``, which takes the qualified names of all test functions to be run.
116 The modules containing the test functions must also be added to the list of modules.
121Package files support comments using the standard Idris singleline ``--`` and multiline ``{- -}`` format.
126Given an Idris package file ``test.ipkg`` it can be used with the Idris compiler as follows:
128+ ``idris --build test.ipkg`` will build all modules in the package
130+ ``idris --install test.ipkg`` will install the package, making it
131 accessible by other Idris libraries and programs.
133+ ``idris --clean test.ipkg`` will delete all intermediate code and
134 executable files generated when building.
136+ ``idris --mkdoc test.ipkg`` will build HTML documentation for your package in the folder ``test_doc`` in your project's root directory.
138+ ``idris --installdoc test.ipkg`` will install the packages documentation into Idris' central documentation folder located at ``idris --docdir``.
140+ ``idris --checkpkg test.ipkg`` will type check all modules in the package only. This differs from build that type checks **and** generates code.
142+ ``idris --testpkg test.ipkg`` will compile and run any embedded tests you have specified in the ``tests`` parameter.
144When building or install packages the commandline flag ``--warnipkg`` will audit the project and warn of any potentiable problems.
146Once the test package has been installed, the command line option
147``--package test`` makes it accessible (abbreviated to ``-p test``).
150 idris -p test Main.idr
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list