*** empty log message ***

git-svn-id: https://svn.parrot.org/parrot/trunk@5133 d31e2699-5ff4-0310-a27c-f18f2fbe73fe

build_tools/build_nativecall.pl

@@ -1,6 +1,34 @@
 #! perl -w
-#
-# Build up the native call routines.
+################################################################################
+# Copyright: 2001-2003 The Perl Foundation.  All Rights Reserved.
+# $Id$
+################################################################################
+
+=head1 NAME
+
+build_tools/build_nativecall.pl - Build up the native call routines
+
+=head1 SYNOPSIS
+
+    % perl build_tools/build_nativecall.pl call_list.txt
+
+=head1 DESCRIPTION
+
+This script creates the Native Call Interface file F<src/nci.c>. It
+parses a file of function signatures of the form:
+
+    <return-type-specifier><whitespace><parameter-type-specifiers> 
+    ...
+
+The types specifiers are documented in F<src/call_list.txt>.
+
+=head1 SEE ALSO
+
+F<src/call_list.txt>.
+
+=cut
+
+################################################################################
 
 my %ret_count;
 %ret_count = (p => [0,0,0,1,0],        # Returning a pointer that we PMC stuff
@@ -389,7 +417,7 @@ sub generate_func_header {
 }
 
 
-=for comment
+=begin comment
 
 This is the template thing
 

build_tools/fingerprint_c.pl

@@ -1,4 +1,29 @@
 #! perl -w
+################################################################################
+# Copyright: 2001-2003 The Perl Foundation.  All Rights Reserved.
+# $Id$
+################################################################################
+
+=head1 NAME
+
+build_tools/fingerprint_c.pl - Create fingerprint.c
+
+=head1 SYNOPSIS
+
+    % perl build_tools/fingerprint_c.pl > src/fingerprint.c
+
+=head1 DESCRIPTION
+
+The F<PBC_COMPAT> file is used to maintain Parrot bytecode
+compatability. During the build process it is parsed by
+F<fingerprint_c.pl> to produce a fingerprint of the state of Parrot.
+
+Note that this is only done for development versions of Parrot, i.e. the
+file F<DEVELOPING> exists. Releases include a non-dynamic fingerprint.c.
+
+=cut
+
+################################################################################
 
 use strict;
 use lib 'lib';

build_tools/jit2h.pl

@@ -1,9 +1,25 @@
-#! /usr/bin/perl -w
-#
-# jit2h.pl
-#
+#! perl -w
+################################################################################
+# Copyright: 2001-2003 The Perl Foundation.  All Rights Reserved.
 # $Id$
-#
+################################################################################
+
+=head1 NAME
+
+build_tools/jit2h.pl - JIT to C
+
+=head1 SYNOPSIS
+
+    % perl build_tools/jit2h.pl <cpu-architecture-name> jit_cpu.c
+
+=head1 DESCRIPTION
+
+This script creates F<jit_cpu.c>. It parses the JIT file for the
+specified CPU architecture type (F<jit/cpu-architecture-name/core.jit>).
+
+=cut
+
+################################################################################
 
 use strict;
 use lib 'lib';

build_tools/ops2c.pl

@@ -1,12 +1,80 @@
-#! /usr/bin/perl -w
-#
-# ops2c.pl
-#
-# Generate a C header and source file from the operation definitions in
-# an .ops file, using a supplied transform.
-#
+#! perl -w
+################################################################################
+# Copyright: 2001-2003 The Perl Foundation.  All Rights Reserved.
 # $Id$
-#
+################################################################################
+
+=head1 NAME
+
+build_tools/ops2c.pl - Parser for .ops files
+
+=head1 SYNOPSIS
+
+    % perl build_tools/ops2c.pl C --core
+
+    % perl build_tools/ops2c.pl C --dynamic myops.ops
+
+=head1 DESCRIPTION
+
+This script uses a supplied transform to create a pair of C header and
+implementation files from the operation definitions found in one or more
+.ops files.
+
+=head2 Transforms
+
+The first command-line argument is the last package name component of a
+subclass of C<Parrot::OpTrans>. These subclasses all have full names of
+the form C<Parrot::OpTrans::*>. An instance of the class is created and
+later consulted for various bits of information needed to generate the C
+code. Each creates a different type of run loop.
+
+=over
+
+=item C
+
+Create the function-based (slow or fast core) run loop.
+
+=item CGoto
+
+Create the C<goto> run loop.
+
+=item CGP
+
+Create the C<goto> and predereferenced run loop.
+
+=item CSwitch
+
+Create the C<switch>ed and predereferenced run loop.
+
+=item CPrederef
+
+Create the predereferenced run loop.
+
+=back
+
+=head2 Options
+
+=over 4
+
+=item C<--dynamic>
+
+Indicate that the opcode library is dynamic.
+
+=item C<--core>
+
+Build the Parrot core opcode library.
+
+=back
+
+=head1 SEE ALSO
+
+C<Parrot::OpTrans::C>, C<Parrot::OpTrans::CGoto>,
+C<Parrot::OpTrans::CGP>, C<Parrot::OpTrans::CSwitch>,
+C<Parrot::OpTrans::CPrederef>, F<build_tools/ops2pm.pl>.
+
+=cut
+
+################################################################################
 
 use strict;
 use lib 'lib';

build_tools/ops2pm.pl

@@ -1,34 +1,54 @@
-#! /usr/bin/perl -w
-#
-# ops2pm.pl
-#
-# Generate a Perl module from the operation definitions in .ops files.
-#
-# The first .ops file on the command line is read in and its name is used to
-# determine the name of the Perl module that will contain the op info.
-#
-# Any remaining .ops files on the command line are read in, and their op
-# info objects are appended, in order, to the op info array obtained from the
-# first .ops file.
-#
-# WARNING: Generating a combined Perl module for a set of .ops files that
-# you do not later turn into a combined opcode table with the same content
-# and order is a recipe for disaster.
-#
-# XXX: The original design of the .ops processing code was intended to be a
-# read-only representation of what was in a particular .ops file. It was
-# not originally intended that it was a mechanism for building a bigger
-# virtual .ops file from multiple physical .ops files. This code does half of
-# that job (the other half is getting them to compile together instead of
-# separately in a *_ops.c file). You can see evidence of this by the way this
-# code reaches in to the internal OPS hash key to do its concatenation, and
-# the way it twiddles each op's CODE hash key after that. If the op and oplib
-# Perl modules are going to be used for modifying information read from .ops
-# files in addition to reading it, they should be changed to make the above
-# operations explicitly supported. Otherwise, the Parrot build and interpreter
-# start-up logic should be modified so that it doesn't need to concatenate
-# separate .ops files.
-#
+#! perl -w
+################################################################################
+# Copyright: 2001-2003 The Perl Foundation.  All Rights Reserved.
+# $Id$
+################################################################################
+
+=head1 NAME
+
+build_tools/ops2pm.pl - Generate Perl module from operation definitions
+
+=head1 SYNOPSIS
+
+    % perl build_tools/ops2pm.pl ops/core.ops ops/bit.ops ...
+
+=head1 DESCRIPTION
+
+The first .ops file on the command line is read in and its name is used
+to determine the name of the Perl module that will contain the op info.
+
+Any remaining .ops files on the command line are read in, and their op
+info objects are appended, in order, to the op info array obtained from
+the first .ops file.
+
+=head2 WARNING
+
+Generating a combined Perl module for a set of .ops files that you do
+not later turn into a combined opcode table with the same content and
+order is a recipe for disaster.
+
+XXX: The original design of the .ops processing code was intended to be
+a read-only representation of what was in a particular .ops file. It was
+not originally intended that it was a mechanism for building a bigger
+virtual .ops file from multiple physical .ops files. This code does half
+of that job (the other half is getting them to compile together instead
+of separately in a *_ops.c file). You can see evidence of this by the
+way this code reaches in to the internal OPS hash key to do its
+concatenation, and the way it twiddles each op's CODE hash key after
+that. If the op and oplib Perl modules are going to be used for
+modifying information read from .ops files in addition to reading it,
+they should be changed to make the above operations explicitly
+supported. Otherwise, the Parrot build and interpreter start-up logic
+should be modified so that it doesn't need to concatenate separate .ops
+files.
+
+=head1 SEE ALSO
+
+F<build_tools/ops2c.pl>.
+
+=cut
+
+################################################################################
 
 use strict;
 use lib 'lib';

build_tools/pbc2c.pl

@@ -1,15 +1,25 @@
-#! /usr/bin/perl -w
-#
-# pbc2c.pl
-#
-# Turn a parrot bytecode file into a C program.
-#
-# Copyright (C) 2001-2002 The Parrot Team. All rights reserved.
-# This program is free software. It is subject to the same license
-# as the Parrot interpreter.
-#
+#! perl -w
+################################################################################
+# TODO: Resolve copyright. See ADDITIONAL section at end of file.
 # $Id$
-#
+################################################################################
+
+=head1 NAME
+
+build_tools/pbc2c.pl - Parrot byte code compiler
+
+=head1 SYNOPSIS
+
+    perl build_tools/pbc2c foo.pbc > foo.c
+
+=head1 DESCRIPTION
+
+Parse the Parrot PackFile listed on the command line, or from standard
+input if no file is named, and turn it into a C implementation file.
+
+=cut
+
+################################################################################
 
 use strict;
 
@@ -341,18 +351,7 @@ sub compile_file {
 
 __END__
 
-=head1 NAME
-
-pbc2c - Parrot byte code compiler
-
-=head1 SYNOPSIS
-
-  pbc2c foo.pbc > foo.c
-
-=head1 DESCRIPTION
-
-Compile the Parrot PackFile listed on the command line, or
-from standard input if no file is named.
+=begin ADDITIONAL
 
 =head1 AUTHOR
 
@@ -362,8 +361,13 @@ =head1 COPYRIGHT
 
 Copyright (C) 2001 Gregor N. Purdy. All rights reserved.
 
+Copyright (C) 2001-2002 The Parrot Team. All rights reserved.
+This program is free software. It is subject to the same license
+as the Parrot interpreter.
+
 =head1 LICENSE
 
 This program is free software. It is subject to the same license
 as the Parrot interpreter.
 
+=end ADDITIONAL

build_tools/vtable_h.pl

@@ -1,6 +1,30 @@
-#!/usr/bin/perl
-
+#! perl -w
+################################################################################
+# Copyright: 2001-2003 The Perl Foundation.  All Rights Reserved.
 # $Id$
+################################################################################
+
+=head1 NAME
+
+build_tools/vtable_h.pl - Create the vtable header
+
+=head1 SYNOPSIS
+
+	% perl build_tools/vtable_h.pl
+
+=head1 DESCRIPTION
+
+This script creates F<include/parrot/vtable.h> from F<vtable.tbl>. It
+uses C<Parrot::Vtable>.
+
+=head1 SEE ALSO
+
+C<Parrot::Vtable>.
+
+=cut
+
+################################################################################
+
 use lib 'lib';
 use Parrot::Vtable;