<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Parrot - PDD 30: Installation</title>
<link rel="stylesheet" type="text/css"
href="../../../resources/parrot.css"
media="all">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<div id="wrapper">
<div id="header">
<a href="http://www.parrot.org">
<img border=0 src="../../../resources/parrot_logo.png" id="logo" alt="parrot">
</a>
</div> <!-- "header" -->
<div id="divider"></div>
<div id="mainbody">
<div id="breadcrumb">
<a href="../../../html/index.html">Home</a> » <a href="../../../html/pdds.html">Parrot Design Documents (PDDs)</a> » PDD 30: Installation
</div>
<h1><a name="PDD_30:_Installation"
>PDD 30: Installation</a></h1>
<h2><a name="Abstract"
>Abstract</a></h2>
<p>This PDD outlines Parrot's installation system and support.
Parrot's core installation system will provide support for binary packages,
a working <code>make install</code> target,
compiled installables,
and Filesystem Hierarchy Standard (FHS) compliant search paths for the installables.</p>
<h2><a name="Version"
>Version</a></h2>
<p>$Revision$</p>
<h2><a name="Synopsis"
>Synopsis</a></h2>
<p>Parrot installation process (from the parrot source directory):</p>
<pre> perl Configure.pl --prefix=/usr
make
make test
make install</pre>
<p>Language installation process (from the language source directory):</p>
<pre> perl Configure.pl --parrot-config=/path/to/parrot_config
make
make test
make install</pre>
<h2><a name="Description"
>Description</a></h2>
<p>Parrot uses FHS compliant install directories by default. Each install location is configurable with options passed to the configure script.</p>
<dl>
<dt><a name="/usr/bin/parrot"
><em>/usr/bin/parrot</em></a></dt>
The main Parrot executable.
<dt><a name="/usr/lib/parrot/<version>/library/"
><em>/usr/lib/parrot/<version>/library/</em></a></dt>
Parrot runtime libraries, corresponds to <em>runtime/parrot/library/</em> in the repository.
<dt><a name="/usr/lib/parrot/<version>/include/"
><em>/usr/lib/parrot/<version>/include/</em></a></dt>
Parrot runtime include files (not C include files), corresponds to <em>runtime/parrot/include/</em> in the repository.
<dt><a name="/usr/lib/parrot/<version>/dynext/"
><em>/usr/lib/parrot/<version>/dynext/</em></a></dt>
Parrot dynamic extension files (for <code>loadlib</code>), corresponds to <em>runtime/parrot/dynext/</em> in the repository.
<dt><a name="/usr/lib/parrot/<version>/languages/"
><em>/usr/lib/parrot/<version>/languages/</em></a></dt>
Parrot language modules. Languages are loaded with <code>load_language 'abc'</code>, which loads <em>/usr/lib/parrot/languages/abc/abc.pbc</em> in an installed Parrot.On the commandline, a language is executed as:
<pre> $ abc hello.bc</pre>
Where <em>abc</em> is a symlink to the <em>parrot</em> executable. On platforms that don't have symlinks, <em>abc</em> may be a copy of the <em>parrot</em> 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 <em>pynie</em> or <em>parrot-python</em> but not <em>python</em>).
<dt><a name="/usr/lib/parrot/<version>/languages/*"
><em>/usr/lib/parrot/<version>/languages/*</em></a></dt>
The languages directories may have subdirectories, including <em>library</em> for their own set of libraries, and <em>dynext</em> for dynamic pmcs and ops, and <em>include</em> 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 <code>mylang</code> HLL named <code>['Foo';'Bar']</code> is stored in <em>/usr/lib/parrot/<version>/languages/<mylang>/library/Foo/Bar.pbc</em>
<dt><a name="/usr/lib/parrot/<version>/tools/"
><em>/usr/lib/parrot/<version>/tools/</em></a></dt>
Parrot tools that don't belong in the bin/ directory and don't belong in the runtime, corresponds to <em>tools/dev/</em> and/or <em>tools/build</em> in the repository. Perl modules used by the tools are installed in <em>/usr/lib/parrot/<version>/tools/lib/</em>.
<dt><a name="/usr/share/doc/parrot/<version>/"
><em>/usr/share/doc/parrot/<version>/</em></a></dt>
Parrot documentation files, generally raw Pod, but possibly also formatted HTML. Has subdirectories for each format of documentation: <em>pod/</em>, <em>html/</em>, etc.
<dt><a name="/usr/include/parrot/<version>/"
><em>/usr/include/parrot/<version>/</em></a></dt>
C header files for Parrot.
<dt><a name="/usr/src/parrot/<version>/"
><em>/usr/src/parrot/<version>/</em></a></dt>
PMC source files needed for building dynamic PMCs.</dl>
<h2><a name="Dependencies"
>Dependencies</a></h2>
<p>Building core Parrot depends on Perl (including <em>perldoc</em>, which may be a separate package), <em>libgdm</em> and <em>libreadline</em>.</p>
<p>Building a language depends on a series of Parrot build tools, installed in <em>/usr/lib/parrot/<version>/tools</em>. These tools will generally not be included in the default <code>parrot</code> package on most systems, languages will require a <code>parrot-dev</code> package to be installed before they can be built.</p>
<h2><a name="Definitions"
>Definitions</a></h2>
<p>The <b>build_dir</b> is the full path where Parrot was built. It is defined in the configuration hash. When building from source the <code>build_dir</code> is also the <code>PARROT_RUNTIME</code> prefix.</p>
<p>An <b>installable</b> 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 <em>install_config.fpmc</em>.</p>
<p>The <b>destination directory</b> is the path of the installed Parrot tree after the prefix (<em>/usr</em>, <em>/usr/local</em>, 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.</p>
<p>The <b>configuration hash</b> is the return value of the global function <code>_config()</code>, generated in <em>config_lib.pasm</em>, and either defined in <em>library/config.pir</em>, or as frozen PMC embedded in the test executable (<em>config.fpmc</em>), the installable executable (<em>install_config.fpmc</em>) or empty for miniparrot (<em>null_config.fpmc</em>).</p>
<h2><a name="Implementation"
>Implementation</a></h2>
<p>A new language is generated by <em>tools/dev/mk_language_shell.pl</em></p>
<p>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 <code>\n</code> is converted to <code>\r\n</code> for MSWin32 nmake. See <a href='TODO'>Parrot::Configure::Compiler</a>.</p>
<h3><a name="Packaging_and_Distribution"
>Packaging and Distribution</a></h3>
<p>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).</p>
<h2><a name="References"
>References</a></h2>
<p>None.</p>
</div> <!-- "mainbody" -->
<div id="divider"></div>
<div id="footer">
Copyright © 2002-2011, Parrot Foundation.
</div>
</div> <!-- "wrapper" -->
</body>
</html>
