[svn:parrot] r38483 - trunk/docs/pdds/draft
allison at svn.parrot.org
allison at svn.parrot.org
Tue May 5 04:59:51 UTC 2009
Author: allison
Date: Tue May 5 04:59:50 2009
New Revision: 38483
URL: https://trac.parrot.org/parrot/changeset/38483
Log:
[pdd] Cleaning up install PDD, preparing to launch out of draft.
Modified:
trunk/docs/pdds/draft/pdd30_install.pod
Modified: trunk/docs/pdds/draft/pdd30_install.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd30_install.pod Tue May 5 04:54:29 2009 (r38482)
+++ trunk/docs/pdds/draft/pdd30_install.pod Tue May 5 04:59:50 2009 (r38483)
@@ -1,16 +1,14 @@
# Copyright (C) 2008-2009, Parrot Foundation.
# $Id$
-=head1 [DRAFT] PDD 30: Installation
+=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. This document also aims to solve the current problem of
-accessing installed source-only files, and to allow the optimization of config
-bootstrapping if a frozen config_hash is already linked.
+installables.
=head2 Version
@@ -20,7 +18,7 @@
Parrot installation process (from the parrot source directory):
- perl Configure.pl --prefix=/usr/lib
+ perl Configure.pl --prefix=/usr
make
make test
make install
@@ -28,6 +26,7 @@
Language installation process (from the language source directory):
+ perl Configure.pl --parrot-config=/path/to/parrot_config
make
make test
make install
@@ -61,11 +60,9 @@
=item F</usr/lib/parrot/E<lt>versionE<gt>/languages/>
-Parrot language modules, corresponds to F<languages/> in the repository.
-
-Languages are loaded with C<load_language 'abc'>, which loads either
-F<languages/abc/abc.pbc> in the build environment of a language in trunk, or
-F</usr/lib/parrot/languages/abc/abc.pbc> in an installed Parrot.
+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:
@@ -81,44 +78,29 @@
=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<dynpmc> for dynamic pmcs.
+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>mylang>/library/Foo/Bar.pbc>
+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.
+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. May have subdirectories F<pod/>, F<html/>, etc.
+Parrot documentation files, generally raw Pod, but possibly also
+formatted HTML. Has subdirectories for each format of documentation:
+F<pod/>, F<html/>, etc.
=back
-Bootstrapping the configuration hash should not read a config file when the
-hash is already contained in the pmc or executable. {{ See RT #57418 [TODO]
-optimize _config to omit .include "library/config.pir" on installables. }}
-The same problem is for every C<.include>, C<loadlib> and C<load_bytecode>
-statement in installed files where the target is not installed. If in doubt
-install the missing library by patching the installation code.
-
-Test executables are binary different to installable executables because of
-this embedded configuration hash. Test executables contain configuration
-hash with the prefix to the build directory, installables to the given
-prefix from Configure.pl. The executables that are tested should always be
-the same as the ones that are installed. Otherwise, subtle bugs can leak
-into the installed executables which can never be caught by the tests.
-
-There are's also a long-standing conflict in building Parrot with an already
-installed shared libparrot.so. See RT #39742.
-For win32 this was solved to put the dll into build_dir, for
-compilers withour rpath support this is still a problem.
-
=head2 Dependencies
Building core Parrot depends on Perl (including perldoc, which may be a
@@ -138,8 +120,7 @@
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>. Custom Python modules have a similar packaging
-problem, which they haven't solved yet.
+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
@@ -153,159 +134,15 @@
(F<config.fpmc>), the installable executable (F<install_config.fpmc>) or empty
for miniparrot (F<null_config.fpmc>).
-=head3 make install
-
-The Parrot build system is currently optimized for building and testing in
-the build directory, but not for building with an already installed
-Parrot. This is complicated by some simple build system bugs. It is also not
-optimized to build and test installables, which should not access libraries
-in the build directory, but in the destination directory.
-
-The short-term goal of this document is to make installation work for
-Parrot, its libraries and tools, and its languages so that packagers can
-provide binary packages for parrot and its languages.
-
-The longer-term goal is a framework so that external libraries and languages
-not within the current parrot source tree can also be properly built, tested
-and installed.
-
-We do not only support GNU make or Win32 nmake but also other platform make
-variants, so we generate the Makefile at first from a generic template.
-
-Currently for Parrot and its libraries the install actions are defined in the
-main Makefile. For the languages the install actions are defined in the
-language's Makefile. {{ See an implementation of this in
-#56554-make-install-lang.patch.}}
-
-One general comment: We need to be careful not to install bytecode
-files in the same directories as executables. The C includes and the PIR
-includes also need to be separate.
-
-C<make install> currently does not work with an already installed shared
-libparrot.so on some platforms. {{See a patch for this in RT #39742.}}
-
-=over 4
-
-=item * bin_dir: Copy installables to the destination directory's F<bin>
-directory as F<parrot-mylanguage>.
-
-=item * script_dir: Optionally copy the main language file F<mylanguage.pbc>
-to the destination directory's F<script> directory. (F</usr/lib/parrot/bin/>
-?)
-
-=item * dynext: Copy shared libraries (groups and ops) to the destination
-directory's F<lib> directory under F</parrot/dynext/>.
-
-The subdirs are currently needed for C<forth> and C<WMLScript>, the other
-language pbc's are F<php_*.pbc>, F<pipplib.pbc> and F<tcllib.pbc>.
-
-=item * lib_dir: Optionally copy include PASM and PIR files to the
-destination directory's F<lib> directory under F<parrot/include/> I<(not
-yet)>.
-
-=item * doc_dir: Copy documentation files to a
-F<$doc_dir/languages/mylanguage/> subdirectory tree.
-
-=item * man_dir: Generate man(1) pages and copy to destination directory's
-F<$man_dir/man1/> directory. {{ what about man(2) and man(3) pages? info_dir
-ditto }}
-
-=item * html_dir: Optionally generate HTML and copy to destination
-directory's F<html> directory, possibly under a language specific
-subdirectory. This should be selectable by a C<Configure> or C<make install>
-option.
-
-=back
-
-=head3 Configuration bootstrapping
-
-Bootstrapping the configuration hash should not read a config file when the
-hash is already contained in the PMC or executable. C<.include
-"library/config.pir"> and C<load_bytecode "config.pbc"> should be omitted on
-installables if possible.
-
-{{NOTE: We need to step back and take a broader view here. Why is
-F<library/config.pir> currently included in the installables? It sounds like
-a hack to work around earlier limitations in the build system. This is an
-ideal opportunity to eliminate the hack. -allison}}
-
-=head3 Accessing not-installed files
-
-B<Makefile and MANIFEST cleanup>
-
-B<Problem:> Various PIR files load source-only PIR, PASM or compiler
-bytecode files, which are not installed in binary packages. This shows up
-when trying to run an installable with the build directory removed or
-renamed.
-
- $ parrot-forth.exe xx
- "load_bytecode" couldn't find file 'languages/forth/tokenstream.pbc'
- current instr.: ' init' pc 942 (forth.pir:9)
- called from Sub 'main' pc 994 (forth.pir:40)
-
- $ parrot-pheme.exe
- "load_bytecode" couldn't find file 'compilers/tge/TGE/Rule.pbc'
- current instr.: 'parrot;TGE;__onload' pc 19 (TGE.pir:94)
- called from Sub 'parrot;Pheme::AST::Grammar;__onload' pc 7175
- (languages/pheme/lib/ASTGrammar.pir:5)
- called from Sub 'parrot;Pheme::Compiler;main' pc -1 ((unknown file):-1)
-
- $ parrot-pipp
- Parrot VM: Can't stat
- /usr/src/perl/parrot/parrot-0.7.0-1/
- build/languages/pipp/src/common/pipplib.pbc, code 2.
- Unable to append PBC to the current directory
- current instr.: 'parrot;Pipp;__onload' pc 47 (src/common/pipp.pir:92)
- called from Sub 'parrot;Pipp;pipp' pc -1 ((unknown file):-1)
-
-B<Fix 1>: Install all deps and make sure that every HLL is installed at
-F<lib_dir/parrot/version/languages>. See also L<pdd31_hll_interop.pod>
-
-{{NOTE: This may be a sign that we need to rethink our language build
-strategy. Trying to glom everything into a single C executable is less than
-ideal. Especially since it causes problems for language interoperability if
-every language is running off its own independent executable. -allison}}
-
-The simple Forth and Pipp problem could be solved by merging the missing
-bytecode files to a single file F<forth.pbc> and generate from this the
-installable.
-
-The simple Pheme problem could be solved by installing also all TGE and
-other compiler bytecode files at the F<parrot/library/compilers> path. Since
-TGE is not used elsewhere anymore, Pheme should be fixed to get rid of
-this. {{NOTE: commonly used libraries should be installed
-somewhere. -allison}}
-
-The same problem is for every C<.include>, C<loadlib> and C<load_bytecode>
-statement in installed files where the target is not installed.
-
-B<Fix 2>: Module system.
-
-Avoid already loaded pbc files.
-
-Source loading PIR statements like C<loadlib> and C<load_bytecode> should
-cache the file name and skip the file if it has already been loaded (as in
-perl5)
-
-B<Fix 3>: pbc_merge fixups
-
-pbc_merge could patch up the bytecode (if possible) to omit loading
-load_bytecode pbc-files which are being merged, but hacking bytecode during
-pbc_merge is not desirable.
-
=head2 Implementation
A new language is generated by F<tools/dev/mk_language_shell.pl>
-The makefiles are generated from a F<config/makefiles/root.in> template,
-which can make use of 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>.
-
-A new F<lib/Parrot/Install.pm> or F<Parrot/Install.pir> library should
-provide the same support as described above and simplify the Makefile and
-installation maintenance. The entry point could be a Makefile.pl or
-Makefile.pir then.
+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>.
=head2 Attachments
@@ -317,6 +154,8 @@
=head2 References
+None.
+
=cut
__END__
More information about the parrot-commits
mailing list