# Copyright (C) 2008-2010, Parrot Foundation. =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 Filesystem Hierarchy Standard (FHS) compliant search paths for the installables. =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 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>versionE<gt>/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 References None. =cut __END__ Local Variables: fill-column:78 End: