PDD 30: Installation

Abstract

This PDD outlines Parrot's installation system and support. Parrot's core installation system will provide support for binary packages, a working make install target, compiled installables, and Filesystem Hierarchy Standard (FHS) compliant search paths for the installables.

Synopsis

Parrot installation process (from the parrot source directory):

  perl Configure.pl --prefix=/usr
  make
  make test
  make install

Language installation process (from the language source directory):

  perl Configure.pl --parrot-config=/path/to/parrot_config
  make
  make test
  make install

Description

Parrot uses FHS compliant install directories by default. Each install location is configurable with options passed to the configure script.

/usr/bin/parrot
The main Parrot executable.
/usr/lib/parrot/<version>/library/
Parrot runtime libraries, corresponds to runtime/parrot/library/ in the repository.
/usr/lib/parrot/<version>/include/
Parrot runtime include files (not C include files), corresponds to runtime/parrot/include/ in the repository.
/usr/lib/parrot/<version>/dynext/
Parrot dynamic extension files (for loadlib), corresponds to runtime/parrot/dynext/ in the repository.
/usr/lib/parrot/<version>/languages/
Parrot language modules. Languages are loaded with load_language 'abc', which loads /usr/lib/parrot/languages/abc/abc.pbc in an installed Parrot.On the commandline, a language is executed as: 
  $ abc hello.bc
Where abc is a symlink to the parrot executable. On platforms that don't have symlinks, abc may be a copy of the parrot executable. On general principles, languages should not install themselves with the same name as their "real" counterpart, but should provide a build option to do so (so, the default installed executable for Python on Parrot should be pynie or parrot-python but not python).
/usr/lib/parrot/<version>/languages/*
The languages directories may have subdirectories, including library for their own set of libraries, and dynext for dynamic pmcs and ops, and include for PIR or PASM includes.It is recommended that languages follow a standard pattern in installing their libraries so a bytecode compiled version of a module in the mylang HLL named ['Foo';'Bar'] is stored in /usr/lib/parrot/<version>/languages/<mylang>/library/Foo/Bar.pbc
/usr/lib/parrot/<version>/tools/
Parrot tools that don't belong in the bin/ directory and don't belong in the runtime, corresponds to tools/dev/ and/or tools/build in the repository. Perl modules used by the tools are installed in /usr/lib/parrot/<version>/tools/lib/.
/usr/share/doc/parrot/<version>/
Parrot documentation files, generally raw Pod, but possibly also formatted HTML. Has subdirectories for each format of documentation: pod/, html/, etc.
/usr/include/parrot/<version>/
C header files for Parrot.
/usr/src/parrot/<version>/
PMC source files needed for building dynamic PMCs.

Dependencies

Building core Parrot depends on Perl (including perldoc, which may be a separate package), libgdm and libreadline.

Building a language depends on a series of Parrot build tools, installed in /usr/lib/parrot/<version>/tools. These tools will generally not be included in the default parrot package on most systems, languages will require a parrot-dev package to be installed before they can be built.

Definitions

The build_dir is the full path where Parrot was built. It is defined in the configuration hash. When building from source the build_dir is also the PARROT_RUNTIME prefix.

An installable is a bytecode or executable file which must not access the build_dir paths. The build_dir path is not available in a binary package. This is solved by generating and linking a special install_config.fpmc.

The destination directory is the path of the installed Parrot tree after the prefix (/usr, /usr/local, or some other platform-specific or custom location). Creating a virtual installation path like this simplifies packaging by installing into a separate install tree and creating a tarball from that tree.

The configuration hash is the return value of the global function _config(), generated in config_lib.pasm, and either defined in library/config.pir, or as frozen PMC embedded in the test executable (config.fpmc), the installable executable (install_config.fpmc) or empty for miniparrot (null_config.fpmc).

Implementation

A new language is generated by tools/dev/mk_language_shell.pl

The makefiles are generated from a makefile template, which can use conditional platform and config logic. The forward slashes are automatically converted to backslashes for MSWin32 and \n is converted to \r\n for MSWin32 nmake. See Parrot::Configure::Compiler.

Packaging and Distribution

Each language, operating system, or distribution is free to package modules in their own way, using their own usual build and install tools. The default distribution format is a tarball containing the source files and a cross-platform build infrastructure (the 'make' variants are a good choice, and can be combined with Autoconf, CMake, Perl, Python, etc. for more complex conditional builds).

References

None.