# Copyright (C) 2008-2009, Parrot Foundation.
# $Id: pdd30_install.pod 40726 2009-08-23 01:18:17Z whiteknight $

=head1 PDD 30: Installation

=head2 Abstract

This PDD outlines Parrot's installation system and support. Parrot's core
installation system will provide support for binary packages, a working C<make
install> target, compiled installables, and FHS compliant search paths for the
installables.

=head2 Version

$Revision: 40726 $

=head2 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

=head2 Description

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

=over

=item F</usr/bin/parrot>

The main Parrot executable.

=item F</usr/lib/parrot/E<lt>versionE<gt>/library/>

Parrot runtime libraries, corresponds to F<runtime/parrot/library/> in the
repository.

=item F</usr/lib/parrot/E<lt>versionE<gt>/include/>

Parrot runtime include files (not C include files), corresponds to
F<runtime/parrot/include/> in the repository.

=item F</usr/lib/parrot/E<lt>versionE<gt>/dynext/>

Parrot dynamic extension files (for C<loadlib>), corresponds to
F<runtime/parrot/dynext/> in the repository.

=item F</usr/lib/parrot/E<lt>versionE<gt>/languages/>

Parrot language modules. Languages are loaded with C<load_language
'abc'>, which loads F</usr/lib/parrot/languages/abc/abc.pbc> in an
installed Parrot.

On the commandline, a language is executed as:

  $ abc hello.bc

Where F<abc> is a symlink to the F<parrot> executable. On platforms that don't
have symlinks, F<abc> may be a copy of the F<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 F<pynie> or
F<parrot-python> but not F<python>).

=item F</usr/lib/parrot/E<lt>versionE<gt>/languages/*>

The languages directories may have subdirectories, including F<library> for
their own set of libraries, and F<dynext> for dynamic pmcs and ops, and
F<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 C<mylang> HLL
named C<['Foo';'Bar']> is stored in
F<usr/lib/parrot/E<lt>versionE<gt>/languages/E<lt>mylangE<gt>/library/Foo/Bar.pbc>

=item F</usr/lib/parrot/E<lt>versionE<gt>/tools/>

Parrot tools that don't belong in the bin/ directory and don't belong in the
runtime, corresponds to F<tools/dev/> and/or F<tools/build> in the
repository. Perl modules used by the tools are installed in
F</usr/lib/parrot/E<lt>versionE<gt>/tools/lib/>.

=item F</usr/share/doc/parrot/E<lt>versionE<gt>/>

Parrot documentation files, generally raw Pod, but possibly also
formatted HTML. Has subdirectories for each format of documentation:
F<pod/>, F<html/>, etc.

=item F</usr/include/parrot/E<lt>versionE<gt>/>

C header files for Parrot.  

=item F</usr/src/parrot/E<lt>versionE<gt>/>

PMC source files needed for building dynamic PMCs.  

=back

=head2 Dependencies

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

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

=head2 Definitions

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

An B<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
F<install_config.fpmc>.

The B<destination directory> is the path of the installed Parrot tree after
the prefix (F</usr>, F</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 B<configuration hash> is the return value of the global function
C<_config()>, generated in F<config_lib.pasm>, and either defined in
F<library/config.pir>, or as frozen PMC embedded in the test executable
(F<config.fpmc>), the installable executable (F<install_config.fpmc>) or empty
for miniparrot (F<null_config.fpmc>).

=head2 Implementation

A new language is generated by F<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 C<\n> is
converted to C<\r\n> for MSWin32 nmake. See
L<Parrot::Configure::Compiler>.

=head3 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).

=head2 Attachments

None.

=head2 Footnotes

None.

=head2 References

None.

=cut

__END__
Local Variables:
 fill-column:78
End: