Author: rurban
Date: Mon Sep 8 12:07:23 2008
New Revision: 30910
Modified:
trunk/docs/pdds/draft/pdd30_install.pod
Log:
[pdd30] incoorporate allisons critic
Modified: trunk/docs/pdds/draft/pdd30_install.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd30_install.pod (original)
+++ trunk/docs/pdds/draft/pdd30_install.pod Mon Sep 8 12:07:23 2008
@@ -27,20 +27,14 @@
=head1 DESCRIPTION
-{{NOTE: Define Parrot's installation system without comparing it to other
-installation systems. I've edited many instances here. -allison}}
-
Parrot's F<MANIFEST> will contain the installation path of all files. The
installation script F<tools/dev/install_files.pl> is driven by this
-definition. The three runtime paths for "include", "library" for
+definition, which contains the filelist and the recommended package if being
+installed at all.
+The three runtime paths for "include", "library" for
load_bytecode and "dynext" for loadlib should end up in the
F<$prefix/lib/parrot> paths. {{NOTE: See #56996-fhs-runtime.patch }}
-{{NOTE: I've edited this paragraph to what I think you meant. But, if this is
-what you meant, I don't agree. The installation paths will be completely
-different on MacOSX, Windows, and various Linux distributions, so the
-information can't be stored in the MANIFEST.}}
-
Parrot and language implementions on top of Parrot may be installed as
self-hosting single-file executables, with the help of merged pbc's and
pbc2exe --install.
@@ -49,24 +43,36 @@
hash is already contained in the pmc or executable. See #57418 [TODO] optimize
_config to omit .include "library/config.pir" on installables.
-The same problem is for every .include, .loadlib and .load_bytecode statement
-in installed files where the target is not installed. This could be solved
-with a module system or with pbc_merge removing not needed .load_bytecode
-statements. {{NOTE: not clear on what you mean here.}}
+The same problem is for every .include, .loadlib and load_bytecode statement
+in installed files where the target is not installed. If in doubt install
+the missing library by patching the installation code.
+Eg. C<load_bytecode 'languages/WMLScript/src/WMLScript.pbc'> should be replaced
+by C<load_bytecode 'WMLScript.pbc'> and F<WMLScript.pbc> should be installed
+to F<library>.
+For C<load_bytecode 'PGE/Text.pbc'> in some lua src we should take care, that
this
+compiler pbc is really installed or if not merge it into the main F<lua.pbc>.
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.
-
-{{NOTE: The executables that are tested should always be the same as the ones
+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. -allison}}
+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 #39742-installed-conflict.patch which adds
the blib/lib path to PATH resp. LD_RUN_PATH.
+=head1 DEPENDENCIES
+
+Before you can C<make installable -C language/lang> or a simple C<make>
+or C<make installable> in the directory F<languages>, you need to
+C<make parrot_utils> and C<make installable> in the parrot build directory.
+
+The languages have no extra dependencies to the required parrot_utils and
+F<src/install_config.fpmc>.
+
=head1 DEFINITIONS
The B<build directory> is the full path where Parrot was built. It is defined
@@ -124,16 +130,21 @@
=item * Optionally copy the main language file F<mylanguage.pbc> to the
destination directory's F<script> directory. (F</usr/lib/parrot/bin/> ?)
-=item * Copy libraries to the destination directory's F<lib> directory under
-F</parrot/dynext/>.
+=item * Copy shared libraries (groups and ops) to the destination directory's
+F<lib> directory under F</parrot/dynext/>.
-=item * Optionally copy PBC files to destination directory's F<lib> directory
-under F<parrot/library/> (only php_ext).
-
-{{NOTE: What do you mean by "only php_ext"? -allison}}
+=item * Copy the main language file F<mylanguage.pbc> to the destination
+directory's F<lib> directory under F<parrot/library/> for HLL
+interoperability. C<load_bytecode "otherlang.pbc"> should succeed.
+
+=item * Optionally copy additional language PBC files to the destination
+directory's F<lib> directory under F<parrot/library/> or a
+F<parrot/library/mylanguage> subdirectory. 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 * Optionally copy include PASM and PIR files to the destination
-directory's F<lib> directory under F<parrot/include/> (not yet).
+directory's F<lib> directory under F<parrot/include/> I<(not yet)>.
=item * Copy documentation files to destination directory's F<doc> directory.
@@ -141,7 +152,8 @@
directory.
=item * Optionally generate HTML and copy to destination directory's F<html>
-directory, possibly under a language specific subdirectory.
+directory, possibly under a language specific subdirectory. This should be
+selectable by a Configure or make install option.
=back
@@ -167,8 +179,8 @@
B<Problem>: C<make test-installable> should copy the make install files away,
out of the build directory, should temporarily rename the build directory, run
a simple test, and remake the build directory back. This will not be possible
-from a make run from within the build directory. So renaming runtime will be
-it. {{Q: What do you mean by "renaming runtime"?}}
+from a make run from within the build directory. So renaming the F<runtime>
+directory during the test might be the best idea.
This is fragile and similar for every language target, so it should be
simplified by a make framework, like include F<Makefile.common> or
@@ -215,7 +227,8 @@
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.
+B<Fix 1>: Install all deps and make sure that every HLL is installed at
+F<library/HLLNAME.pbc>
{{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
@@ -227,43 +240,30 @@
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. {{NOTE:
+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 .include, .loadlib and .load_bytecode statement
in installed files where the target is not installed.
-This could also be solved with a module system or with pbc_merge removing
-those statements. {{NOTE: We don't want to be hacking up the bytecode as we
-merge it. -allison}}
-
B<Fix 2>: Module system.
Avoid already loaded pbc files.
Source loading PIR statements like .loadlib and .load_bytecode should a) cache
the file name and skip the file if it has already been loaded b) add
-.load*_once sisters as in php - .load_bytecode_once and .loadlib_once
+.load*_once sisters as in php - .load_bytecode_once and .loadlib_once.
+This is not preferred. It might be added later on, but parrot core should not
+rely on it.
{{NOTE: option (a) strongly preferred. -allison}}
B<Fix 3>: pbc_merge fixups
-pbc_merge should patch up the bytecode (if possible) to omit
-loading .load_bytecode pbc-files which are being merged.
-
-{{NOTE: not desirable}}
-
-B<Fix 4>: .include_bytecode
-
-Introduce a new op .include_bytecode, which works like .include, but
-on the bytecode level.
-
-{{NOTE: How .include works is by copying the entire text of the include file
-into the destination file. This really isn't desirable, as it means absorbing
-memory for duplicate code instead of compiling it once and loading it as a
-library. And, it means an op that works like .include but for bytecode would
-be impossible. -allison}}
+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.
=head1 ATTACHMENTS
@@ -275,10 +275,11 @@
=head1 REFERENCES
-The mentioned patches against SVN HEAD are at
-http://code.google.com/p/cygwin-rurban/
- source/browse/trunk/release/parrot/patches
+{{The mentioned single patches against SVN HEAD are at
+http://code.google.com/p/cygwin-rurban/source/browse/trunk/release/parrot/patches
The patches in the tickets are always too old.
+The cygwin070patches branch contains all the mentioned fixes, so it is really a
+"make_install" branch.}}
#nnnnn references tickets in
http://rt.perl.org/rt3/Ticket/Display.html?id=nnnnn
