# Packages

PM3 is distributed as a set of packages. Each package is contained in a single directory, named after the package, which conforms to a standard structure. The top level directory should contain a `src` subdirectory containing Modula-3 source files. The compiler, `m3build`, also creates a derived platform directory for each platform on which the package is built. Besides the `src` and platforms subdirectories, a package may contain other packages to form a package hierarchy. These other packages are often tutorials or tests related to the containing package.

There are three primary types of packages: program, library, and other. An other package contains a collection of sources, often documentation; it builds nothing. A program package constructs a single executable program by compiling and linking the contents of a set of source packages. Similarly, a library package constructs a single library from a set of source packages.

The `m3makefile`, that describes the package, resides in the `src` subdirectory of the package. Although it is common for all the Modula-3 sources to also reside in the src directory, they may be distributed in a more complex directory structure rooted at `src`.

The `m3makefile` for a source package simply lists the pieces of source that are to be included in programs or libraries that include the source package. It ends with a single `OtherPackage()` invocation.

The `m3makefile` for a program package names the sources needed to build the program, and the packages that it uses to satisfy its imports. It ends with a single `program()` or `Program()` invocation. See the example.

The `m3makefile` for a library package names the sources to be included in the library, and the packages that it uses to satisfy its imports. It ends with a single `library()` or `Library()` invocation.

Note that as in a program, all the imports of a package must be satisfied. If a package A builds a library and any of the objects in that library import interfaces from another library package B, then `import(B)` must be specified in A's `m3makefile`.

A package, once compiled with `m3build`, may have its exported (visible) files installed in a package repository with m3ship. By default, `m3ship` installs packages in the public repository (e.g. `/usr/local/lib/m3/pkg`). Note that on some systems, you must have special privileges to install public packages.