Author: allison Date: Sat Sep 6 02:24:42 2008 New Revision: 30814 Modified: trunk/docs/pdds/draft/pdd30_install.pod trunk/docs/pdds/draft/pdd31_hll_interop.pod
Log: [cage] Update two draft PDDs so they meet the coding standards. Modified: trunk/docs/pdds/draft/pdd30_install.pod ============================================================================== --- trunk/docs/pdds/draft/pdd30_install.pod (original) +++ trunk/docs/pdds/draft/pdd30_install.pod Sat Sep 6 02:24:42 2008 @@ -8,10 +8,10 @@ =head1 ABSTRACT This PDD defines Parrot's installation details. The goal is to provide binary -packages, a working C<make install> for parrot, the installables, FHS compliant -search paths for the installables and solving the problem of not accessing -installed source-only files and the optimization of config bootstrapping -if a frozen config_hash is already linked. +packages, a working C<make install> for parrot, the installables, FHS +compliant search paths for the installables and solving the problem of not +accessing installed source-only files and the optimization of config +bootstrapping if a frozen config_hash is already linked. =head1 VERSION @@ -26,28 +26,28 @@ =head1 DESCRIPTION -Parrot installation mechanisms are more powerful than perl5's. -MANIFEST contains also the end location, tools/dev/install_files.pl is driven -by this definition. -The three runtime paths for "include", "library" for load_bytecode and "dynext" -for loadlib should end up in the $prefix/lib/parrot paths. -See #56996-fhs-runtime.patch +Parrot installation mechanisms are more powerful than perl5's. MANIFEST +contains also the end location, tools/dev/install_files.pl is driven by this +definition. The three runtime paths for "include", "library" for +load_bytecode and "dynext" for loadlib should end up in the $prefix/lib/parrot +paths. See #56996-fhs-runtime.patch Contrary to perl5, parrot and its 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. Bootstrapping the config hash should not read a config file when the hash is -already contained in the pmc or executable. See #57418 [TODO] optimize -_config to omit .include "library/config.pir" on installables. +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. +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. Test executables are binary different to installable executables because of -this embedded config hash. Test executables contain config hash with -the prefix to the build_dir, installables to the given prefix from Configure.pl. +this embedded config hash. Test executables contain config hash with the +prefix to the build_dir, installables to the given prefix from Configure.pl. 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 @@ -61,16 +61,18 @@ have a similar packaging problem, which they haven't solved yet. B<build_dir> is the full path where parrot was built. It is defined in the -config hash. When building from source build_dir is also the PARROT_RUNTIME prefix. +config hash. When building from source build_dir is also the PARROT_RUNTIME +prefix. -B<DESTDIR> is the end location of the parrot tree in front of the prefix -(/usr or /usr/local). This allows packaging by installing into a seperate -install tree and do a tar cf there. +B<DESTDIR> is the end location of the parrot tree in front of the prefix (/usr +or /usr/local). This allows packaging by installing into a seperate install +tree and do a tar cf there. The B<config 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>). +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>). =head1 IMPLEMENTATION @@ -78,8 +80,8 @@ The parrot build system is optimized for building and testing in the build_dir, but not for building with an already installed parrot due to simple -build system bugs, and not optimized to build and test installables, which should -not access the libraries in the build_dir, but in the DESTDIR. +build system bugs, and not optimized to build and test installables, which +should not access the libraries in the build_dir, but in the DESTDIR. The goal is to make install work for parrot, the utils, and all the languages. For parrot and its utils the install actions are defined in the main Makefile, @@ -91,22 +93,23 @@ make install actions for a language lang: - copy installables to DESTDIR/bin_dir as parrot-lang - optionally copy lang.pbc to DESTDIR/script_dir (/usr/lib/parrot/bin/ ?) - copy libraries to DESTDIR/lib_dir/parrot/dynext/ - optionally copy pbc's to DESTDIR/lib_dir/parrot/library/ (only php_ext) - optionally copy include pasm and pirs to DESTDIR/lib_dir/parrot/include/ (not yet) - copy docs to DESTDIR/doc_dir/ - generate a man(1) page and copy to DESTDIR/man_dir/ - optionally generate html and copy to DESTDIR/html_dir/lang/ + * copy installables to DESTDIR/bin_dir as parrot-lang + * optionally copy lang.pbc to DESTDIR/script_dir (/usr/lib/parrot/bin/ ?) + * copy libraries to DESTDIR/lib_dir/parrot/dynext/ + * optionally copy pbc's to DESTDIR/lib_dir/parrot/library/ (only php_ext) + * optionally copy include pasm and pirs to + DESTDIR/lib_dir/parrot/include/ (not yet) + * copy docs to DESTDIR/doc_dir/ + * generate a man(1) page and copy to DESTDIR/man_dir/ + * optionally generate html and copy to DESTDIR/html_dir/lang/ =head2 make installable -C languages/lang This creates a pbc or exe linked to F<install_config.fpmc>, and this executable should not access the build_dir/runtime/parrot paths. -A pbc may be optionally merged with F<install_config.fpmc>, an exe -is just linked with C<pbc_to_exe --install>. +A pbc may be optionally merged with F<install_config.fpmc>, an exe is just +linked with C<pbc_to_exe --install>. =head2 make test-installable -C languages/lang @@ -118,9 +121,9 @@ B<Implementation>: I<TODO> -B<Problem>: C<make test-installable> should copy the make install files away, out -of the build_dir, should temporarily rename build_dir, run a simple test, and -remake the build_dir back. This will not be possible from a make run from +B<Problem>: C<make test-installable> should copy the make install files away, +out of the build_dir, should temporarily rename build_dir, run a simple test, +and remake the build_dir back. This will not be possible from a make run from within the build_dir. So renaming runtime will be it. This is fragile and similar for every language target, so it should be @@ -130,15 +133,14 @@ =head2 _config bootstrapping Bootstrapping the config hash should not read a config file when the hash is -already contained in the pmc or executable. -.include "library/config.pir" and .load_bytecode "config.pbc" should be -omitted on installables if possible. +already contained in the pmc or executable. .include "library/config.pir" and +.load_bytecode "config.pbc" should be omitted on installables if possible. =head2 Accessing not-installed files B<Problem:> Various pir files load source-only .pir, .pasm or compiler .pbc -files, which are not installed in binary packages. -This shows up when trying to run an installable with the build_dir removed or renamed. +files, which are not installed in binary packages. This shows up when trying +to run an installable with the build_dir removed or renamed. $ parrot-forth.exe xx "load_bytecode" couldn't find file 'languages/forth/tokenstream.pbc' @@ -154,7 +156,8 @@ $ 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. + /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) @@ -177,9 +180,9 @@ Avoid already loaded pbc files. -Source loading PIR statements like .loadlib and .load_bytecode should -a) hash its arg and skip the file if already loaded (hash lookup) -b) add .load*_once sisters as in php - .load_bytecode_once and .loadlib_once +Source loading PIR statements like .loadlib and .load_bytecode should a) hash +its arg and skip the file if already loaded (hash lookup) b) add .load*_once +sisters as in php - .load_bytecode_once and .loadlib_once B<Fix 3>: pbc_merge fixups @@ -202,10 +205,12 @@ =head1 REFERENCES The mentioned patches against SVN HEAD are at -http://code.google.com/p/cygwin-rurban/source/browse/trunk/release/parrot/patches +http://code.google.com/p/cygwin-rurban/ + source/browse/trunk/release/parrot/patches The patches in the tickets are always too old. -#nnnnn references tickets in http://rt.perl.org/rt3/Ticket/Display.html?id=nnnnn +#nnnnn references tickets in +http://rt.perl.org/rt3/Ticket/Display.html?id=nnnnn =cut Modified: trunk/docs/pdds/draft/pdd31_hll_interop.pod ============================================================================== --- trunk/docs/pdds/draft/pdd31_hll_interop.pod (original) +++ trunk/docs/pdds/draft/pdd31_hll_interop.pod Sat Sep 6 02:24:42 2008 @@ -80,16 +80,16 @@ -- rgr, 31-Jul-08. The language will never provide a wrapper for its subs. For the most part, -wrappers will be unnecessary. Where a wrapper is desired to make a library from -some other language act more like a "native" library, the person who desires -the native behavior can implement the wrapper and make it publically available. ---allison }} +wrappers will be unnecessary. Where a wrapper is desired to make a library +from some other language act more like a "native" library, the person who +desires the native behavior can implement the wrapper and make it publically +available. --allison }} {{ I am discovering that there are five different viewpoints here, corresponding to the five layers (including "plain Parrot") of the diagram above. I need to make these viewpoints clearer, and describe the -responsibilities of each of these parties to each other. -- rgr, -31-Jul-08. }} +responsibilities of each of these parties to each other. -- rgr, 31-Jul-08. +}} Languages are free to implement the stub and wrapper layers (collectively called "glue") as they see fit. In particular, they may be inlined in the @@ -132,7 +132,8 @@ call intra-language subs, they should be very sure they understand that language's calling conventions. -{{ It's not possible to define a sub that can't be called externally --allison }} +{{ It's not possible to define a sub that can't be called externally +--allison }} =back @@ -202,8 +203,8 @@ a string as a parameter. {{ Common Lisp (for example) will have its own set of type relationships, -because it will have its own set of types. There will be no "remapping" of core -types --allison }} +because it will have its own set of types. There will be no "remapping" of +core types --allison }} The language that owns the multisub gets to define the type hierarchy and dispatch rules used when it gets called. In order to handle objects from @@ -275,11 +276,11 @@ floating-point result from Common Lisp code that happens to get two integers from Perl or Lua (or both!). -{{ Not a bug, it's the expected result. Divide operations are multi-dispatched. -If you pass two Common Lisp integers into a divide operation in Perl 5, it'll -search for the best matching multi, and if it finds one for Common Lisp -integers (an exact match), it'll run that and return a Common Lisp ratio. ---allison }} +{{ Not a bug, it's the expected result. Divide operations are +multi-dispatched. If you pass two Common Lisp integers into a divide +operation in Perl 5, it'll search for the best matching multi, and if it finds +one for Common Lisp integers (an exact match), it'll run that and return a +Common Lisp ratio. --allison }} Even though these languages all use "/" to represent division, they do not all mean the same thing by it, and similarly for most (if not all) other built-in @@ -332,8 +333,8 @@ of these. {{ It is perfectly fine for a Lisp arithmetic operator to return a RATIONAL -subtype. Please don't define methods for a pile of operations that already have -vtable functions --allison }} +subtype. Please don't define methods for a pile of operations that already +have vtable functions --allison }} The other aspect is extending other languages' arithmetic to do something reasonable with our exotic types. If we're lucky, Parrot will provide a basic @@ -374,8 +375,8 @@ they continue to work if passed a subclass by a call from a different language). -{{ Define them on the class that makes sense. There's no point in targeting any -particular level of the inheritance hierarchy. --allison }} +{{ Define them on the class that makes sense. There's no point in targeting +any particular level of the inheritance hierarchy. --allison }} =item 3. @@ -387,9 +388,9 @@ =back -{{ The fundamental rule is to implement your language in the way that makes the -most sense for your language. Language implementors don't have to think about -interoperability. --allison }} +{{ The fundamental rule is to implement your language in the way that makes +the most sense for your language. Language implementors don't have to think +about interoperability. --allison }} The rest of this section details exceptions and caveats in dealing with scalar data types. @@ -499,9 +500,9 @@ could Ruby do with a Scheme list when it can't even get to the Scheme C<car> function? -{{ Except that Ruby would never even get a Scheme list in the first place if it -hadn't loaded a Scheme library of some sort. And, being a list, the Scheme list -would still support the standard vtable functions for lists. --allison }} +{{ Except that Ruby would never even get a Scheme list in the first place if +it hadn't loaded a Scheme library of some sort. And, being a list, the Scheme +list would still support the standard vtable functions for lists. --allison }} {{ Methinks the right thing would be to define a common introspection API (a good thing in its own right). Scheme and Ruby should each define their own @@ -514,9 +515,9 @@ not need anything out of the ordinary, from either language or the called module author. -- rgr, 29-Jul-08. }} -{{ There is a common introspection API, the 'inspect' vtable function. But what -you're describing here isn't introspection, it's actually the standard vtable -functions. --allison }} +{{ There is a common introspection API, the 'inspect' vtable function. But +what you're describing here isn't introspection, it's actually the standard +vtable functions. --allison }} =head3 Defining methods across language boundaries @@ -531,8 +532,8 @@ language uses a significantly different metamodel, simply adding the C<:method> pragma may not cut it. -{{ No, the C<:method> flag is always all you need to define a method. The class -object you add the method to determines what it does with that method. +{{ No, the C<:method> flag is always all you need to define a method. The +class object you add the method to determines what it does with that method. --allison }} There are two cases: (1) The calling language is adding a new method, which @@ -556,8 +557,8 @@ language (from whose namespace the caller must find the multisub), multis are more loosely coupled to their original language. -{{ Well, the semantics of the language that defined the multisub also determine -how it is found and invoked. --allison }} +{{ Well, the semantics of the language that defined the multisub also +determine how it is found and invoked. --allison }} The cases for multimethods are similar, though: (1) If the calling language method is specialized to classes that appear only in the calling module, then @@ -594,6 +595,10 @@ the primary focus of language interoperability. Using libraries from other languages is. --allison }} +=head1 REFERENCES + +None. + =cut __END__
