PowerAda abuild

From OC Systems Wiki!
Jump to: navigation, search


NAME

abuild - automatically build PowerAda programs

SYNOPSIS

abuild [ options ] [ srcfile | unit | objfile ]...

DESCRIPTION

abuild provides convenient combinations of program-building actions to speed the recompiling and binding of programs.


Note
aprojbuild should be used instead of abuild for all compilation done within a project.

When a list of files is specified, abuild:

  • creates a library and/or working sublibrary, if necessary,
  • determines which files are not currently in the library;
  • of those that are in the library, determines which are newer than the compiled version;
  • gets compilation options from the library for all previously-compiled files.
  • determines a compilation order for the new files;
  • invokes the compiler for each file in turn;
  • if a file cannot be compiled because of obsolete supporters, automatically recompiles those supporters;

If one of the bind options, -m, -x, or -b, is specified, and no errors have occurred during previous compilations:

  • the bind operation is attempted.
  • if the bind fails due to obsolete units, automatically recompiles those units.
  • the default executable file name is the name of the main unit, rather than "a.out" which is the default for the ada command. This may be overridden with the -o option.

If unit names are specified instead of file names (indicating by the -u option), all units which must be compiled to make the specified units current are compiled; that is, the units themselves and the supporting specs of those units.

See EXAMPLES below for option combinations for common tasks.

OPTIONS

-a
Compiles all files, not just those newer than in the library. If -u is specified, compiles all units, not just those that are obsolete.
-Boptions
Specifies bind options (valid only with -b, -m, or -x). This may be specified multiple times, but the options string may contain no dashes or spaces, e.g.,-B qstack_limit=env -B qheap_limit=env
-b unit
Binds a program with main subprogram unit after compiling specified source, if any, and after compiling any units required to bind unit.
-C options
Specifies compile options which override those in library. This may be specified multiple times, but the options string may contain no dashes or spaces, e.g., -C OS -C qarch=ppc

yieldsada -OS -qarch=ppc

The special string none may be specified after -C to indicate that no options are to be passed on the ada command line, i.e., -C none
-coptions
Specifies specify compile options for files not found in the library and not individually overridden by options given on standard input (see "files" below). This may be specified multiple times, but the options string may contain no dashes or spaces, e.g., "-cPk" yields "ada -Pk".
-Doptions
Specifies asrcdep (compilation order tool) options:
  • -DF - "fast", uses only initial WITH list to determine supporters;
  • -Dg - ignores dependencies on nested generics;
  • -Di - ignores pragma inline dependencies
  • -Dgi, -Dig - ignores both inline, nested generic dependencies
-d
Does NOT automatically recompile any out-of-date units; instead just writes obsolete units to standard output and returns 27 (see also -p).
-e
Allows the user to edit failures as they occur using the editor specified by $EDITOR, or /bin/vi if EDITOR is not defined. Note that the editor command used must terminate before abuild continues. This is mutually exclusive with the -F and -I options.
-F
Ignores compilation errors when they occur; otherwise returns the compiler return code (mutually exclusive with -e).
-f
Does not reorder initial files/units into compilation order, but compiles them in the order presented on the command line and/or standard input.
-h
Gives version and brief command line help.
-I
Indicates that files and compile options, (or unit names if -u) are to be read from standard input after reading all command line parameters. The -e option cannot be used with -I because of conflicts on standard input.
-i objfile
Passes "-i objfile" on the ada command line when binding.
-L library
library is the file name of the Ada program library. The default of alib.list is used if this option is not specified.
-l
Does not check for obsolete units before bind. Used with -b, -x.
-m
Binds against the most recently compiled library subprogram in the working sublibrary. Unlike ada -m, the main need not be compiled in the current command or be the last unit compiled
-n
Does not do any compiles, just lists the command line of the compiles to be attempted to standard error.
-o file
Specifies that file is name of the executable to be produced by the bind operation; valid only with -b, -m,-x.
-p
Does not automatically recompile out-of-date units that are in sublibraries other than the working sublibrary; instead just writes obsolete units to standard output and returns 27 (see also -d).
-q
Quicklink after compiling (valid only with -x, not -b or -m). See EXAMPLES for more information.
-Q
Quicklink, ignoring some errors (unsafe) (valid only with -x). See EXAMPLES for more information.
-U
Updates (makes current) all units in the working sublibrary after compiling. This is equivalent to areport | abuild -uI. This analysis is done after all compiles have successfully completed, so abuild -vU *.ada will bring a sublibrary up-to-date relative to changed local source and any ancestor sublibraries that may have changed.
-u
Indicates that the parameters on the command line and/or specified on input are unit names, not file names. NOTE: when unit names are specified on standard input, no options may be specified.
-w sublibrary
sublibrary is the path name of a PowerAda sublibrary that is to be used as the working sublibrary. This is only valid with the -x option. Abuild attempts to create this sublibrary if it does not exist. The sublibrary is added to the "top" of the library extracted from the executable file if it is different from the working sublibrary that is already there.
-x executable_file
executable_file is the path name of the executable file from which to obtain the program library (unless -L was specified) and the main program name. Note that you must have write access to the working sublibrary in the library extracted from the executable; mutually exclusive with -b.
-0 (zero)
return exit status of zero rather than ten if the only "error" is that no compilations were performed (see RETURN CODES below.)

PARAMETERS

srcfile
Source files to be considered for compilation. If specified on standard input, each line may be of the format: filename [ ada_options...] [ -- comment ]
where ada_options are command line options that would be specified on the ada command. Such options override the options contained in the library or those specified with the abuild -c option. If the value -none is specified as the only option, this indicates that no command line options are to be placed on the ada command for that file.
unit
Parameters are interpreted as compilation unit names if the -u option is specified on the command line. If specified on standard input, each line may be of the format: unitname [ -- comment ]
Note that in this case no individual options may be specified. Note also that, because comments are allowed, the output of the areport command is accepted. Furthermore, all input is read before processing begins, so unlike ada -I, areport output may be piped directly into abuild.
objfile
Object and archive files to be included linked into the executable. These are passed verbatim on the ada command line.

NOTES

In some cases it is possible to avoid re-binding a program that has had minor changes made to a few bodies by using the quicklink switch (-q or -Q). A quicklink uses the linker to combine a previously bound executable with recompiled code. In order to use quicklink your situation must meet the following requirements:

  • An executable that was originally created by a full bind must exist.
  • The changed units must be bodies of subprograms or packages.
  • The changed units must not be part of a generic.
  • The changed units must not have had pragma Inline applied to them.

You must supply an executable (via the -x switch) along with the files to be recompiled as input to abuild. If you do not indicate an output executable (via the -o switch) the input executable's name will be used (the replacement will only be done if a successful return code is generated by the linker).

Abuild will recompile any subunits of the units named on the input line.

The re-link can fail for couple of reasons:

  • The new code you compiled referenced a subprogram in another package that had not been previously referenced. Since the newly referenced subprogram was not in the original executable it is now missing. If you wanted to continue to use the quick-link feature you can add the other package to the abuild command line and attempt a quick link again.
  • You don't have write access to the file you have indicated for the output of the quicklink.

RETURN CODES

 0 - compiles/binds completed successfully
 1 - invalid abuild parameters
     command line too long, or
     invalid license
 2 - file not found
 3 - library cannot be opened
 4 - missing main unit
 7 - circular dependency
10 - no files were compiled (if return code would
     otherwise be 0, or -F was specified)
13 - syntax or semantic error in compilation
99 - unknown error

FILES

$POWERADA/bin/abuild - the abuild program
$POWERADA/bin/ada, asrcinfo, asrcdep -
        tools invoked by the abuild program

ENVIRONMENT VARIABLES

POWERADA

This must be defined and indicate the powerada/ada95 directory in the PowerAda installation.

POWERADA_BASELINES

Names a baselines file identifying aliases for baseline projects.

EDITOR

This is used to determine which editor to use. If undefined,
/bin/vi is used.

EXAMPLES

abuild -ve *.ada -b main

Determine which of *.ada are new or have changed since compiled into the working sublibrary, and compile them in compilation order, recompiling obsolete units when necessary. All compilations are done into the working sublibrary, which must exist. When all compilations have completed successfully, bind a program with main unit main, producing an executable file main. The -e flag indicates that, if an error occurs, invoke: $EDITOR error_file source_file, then prompt to retry compilation. The -v flag gives verbose progress messages.

abuild -x /project/bin/project_prog -w adalib -o my_prog \
       my_fix.ada

Create a temporary library list by extracting the list saved in the executable project_prog, adding adalib as the working sublibrary (if not there already), and creating adalib if it does not exist. Then compile in my_fix.ada and, if successful, rebind the main unit of project_prog as the local executable file my_prog.

areport | abuild -auI -CPk

Recompile all units in the working sublibrary with the compiler command ada -Pk.

abuild -aidfI -cOS <<EOF
safe.ada -Pk       -- no debug, source, or optimize
optimized.ada      -- optimize this one
default.ada -none  -- use no options
EOF

Equivalent to the following:ada -kP safe.ada
ada -OS optimized.ada
ada default.ada

ls *.ada | abuild -vIU

Compile all new and changed files in the current directory into the working sublibrary, then recompile any obsolete units in the working sublibrary. If the source for each sublibrary is in the sublibrary's directory (a preferred organization), and the user has write access to all sublibraries, then one can update an entire library alib.list in place as follows:

# parameters:
LIBRARY=alib.list
#
# put sublibraries in reverse order, top one contains main
# subprogram
SUBLIST=
cat $LIBRARY | sed "s/--.*$//" | grep -v "^ *$" |\ 
while read SUBLIB
do
   SUBLIST="$SUBLIB $SUBLIST"
done
for SUBLIB in $SUBLIST
do
   cd 'dirname $SUBLIB'
   ls *.ada | abuild -vUI
done
#
# now in directory containing main program's sublibrary
abuild -m

SEE ALSO

ada, aprojbuild, areport, powerada.

BUGS/LIMITATIONS

A maximum of 10000 files or units may be specified.

Abuild does not read currently the powerada preferences files which describe the editor, compile and bind options used by the powerada Build Manager.

Abuild is superceded by aprojbuild in PowerAda version 3.

See Problems and Questions at the beginning of this Appendix.