This chapter describes the Babel code generator and its command line options.
Babel is a compiler. It takes symbols and their interfaces as input and generates either code or a given textual representation. These interfaces may be specified in either Scientific Interface Definition Language (SIDL) or Extensible Markup Language (XML). The form the output takes depends upon the options specified on the command line. Refer to the Section 4.2 for details on command line options. More information on the supported bindings can be found in Part II of this document.
The entire Babel code generator is written in Java and
compiled into a jar file. For convenience, a small script
called babel is provided that should
set the appropriate environment variables and invoke
the Java Virtual Machine on the jar file. To test that
the script and jar file are working together properly,
simply type babel --help.
Babel requires exactly one of the following
mutually exclusive arguments on the command line unless you use the
--multi option.
--help : Print options to stdout.
--version : Print version of Babel.
--text=form :
Generate text equivalent (“sidl” or “xml”) of associated
package(s) or generate interface documentation with “html”.
--client=lang :
Generate client, or proxy, classes to access library.
--server=lang :
Generate the server and client classes to implement the library.
--parse-check :
Check the SIDL file only.
By far, the three most common uses of Babel will be to generate the Client-side proxies, Server-side implementations, and XML associated with the SIDL file. The last option is essentially used internally when the Babel runtime library is being developed.
The --multi option lets you generate multiple
targets for a given set of files in a single run. Put it first on the
command line, each --client or --server can have a different set of settings.
Additionally, there are a few supplemental arguments that complete the picture.
--output-directory=dir :
Specifies the root directory associated with the
generated files. The default setting is
the current working directory.
--generate-hooks :
Generate additional methods in the implementation files that
allow developers to put additional code to be called before
and after the actual method call. These hooks are useful for
implementation-specific method invocation instrumentation.
Their execution can be disabled at run-time.
--generate-subdirs :
Generates files in a directory tree
matching the packaging scope of the SIDL file. This
is on by default for languages that have this
requirement, such as Java and Python, but off
by default for languages that have no such
requirement. Hence, code generation for only the
latter languages (e. g. C, C++, F77, F90) is affected
by this option.
--generate-subdirs-off :
Turn the --generate-subdirs
feature off. This is useful with
--multi option.
--short-file-name :
When the --generate-subdirs and
--short-file-names options are
used simultaneously, the generated file names will not include
package names, just the class or interface symbol. Thus,
either long or short names must be used in all clients or
servers that have interdependencies; mixing short and long
names will result in compile and/or runtime errors.
--repository-path=path :
Specifies a semicolon-separated list of directories,
or URLs1
to search for XML Type descriptions. The need for
these XML types is to resolve references in the
SIDL file.
This option can be used multiple times on the same
command line. If appropriate, the Babel script
adds the default repository path to the command line
before dispatching to the Java Virtual Machine.
--no-default-repository :
Prohibits the use of the default repository
in resolving symbols.
--rename-splicers :
To improve some of the Babel 1.0 splicer blocks names were changed
in Babel 1.4. This switch will automatically rename Babel 1.0
splicer blocks to their new Babel 1.4 names.
--suppress-contracts :
Refrain from generating checks associated with contracts
specified in the SIDL file.
--suppress-ior :
Refrain from generating IOR source and header files.
--suppress-timestamp :
Suppresses the insertion of meta-information that
could result in generated files that would otherwise
not differ from prior executions on the same, unchanged
input file.
Typically Babel inserts meta-information such as
creation time into files it generates. Although
this information is useful, it does result in the
creation of excessive changes when using version control systems.
--exclude=regex :
This options can be used multiple times. Each time you
add a regular expression that will be used to exclude
symbols from code generation. No code or XML will be
generated for any symbol matching the user provided
regular expression. This command line option requires
version 1.4.0 or later of the Java runtime environment.
--cca-mode :
This flag changes the contents of splicer blocks to
match the requirements for the Common Component Architecture (CCA).
Unimplemented methods throw exceptions, and there are some
extra indications for Bocca about which sections still
require editing.
--comment-local-only :
This option reduces the amount of comments in stub
C header files. It will only include the doc comments
for locally defined methods. It will not include doc
comments for inherited methods.
--hide-glue :
This option causes all non-impl files to be generated
in a glue/ subdirectory. This reduces the
“clutter” in the current directory.
--hide-glue-off :
Turn off the --hide-glue setting.
--language-subdir :
This options causes all generated files to be stored in a
language-dependent subdirectory; if the --generate-subdirs option is also used, the language
directory will be at the bottom of the hierarchy.
--language-subdir-off :
Turn the --language-subdir setting
off.
--make-prefix=prefix :
The string prefix is prepended to the name of
babel.make and the symbols defined inside babel.make
to allow Babel to be run multiple times in a single directory without
overwriting files.
--makefile :
This instructs Babel to generate a sample GNU Makefile named GNUmakefile.
The sample GNU Makefile uses babel-config to determine the appropriate build
flags. It’s meant to be a simple, example Makefile, and it will likely require
editing before incorporating it in a larger project build. It may not work
correctly with other options that change where files are
generated such as the --hide-glue option.
--exclude-external :
This option causes code to be generated only for the symbols
specified on the command line. If you list a SIDL file
on the command line, all the symbols it contains will be
included. No code is generated for symbols
on which the users symbols depend. This behavior is now the default
behavior, so this option is not usually required.
--include-referenced :
This option causes code to be generated for symbols specified
on the command line and for all symbols referenced by symbols
on the command line. It is the opposite behavior to
--exclude-external.
--cxx-ior-exception :
Earlier versions of the Babel C++ bindings checked the IOR
pointer in a given stub before making any calls on it. If the IOR was
null, a NullIORException was thrown. It was later found that in
certain cases these checks were taking an inordinent amount of time,
and since C++ does not normally check pointers before dereferencing
them, it was decided that this feature was out of line with the spirit
of C++. However, since some code had already been written that used
this feature, we could not completely eliminate the checks.
Therefore, this command line option was added. Calling babel
with it will generate C++ stubs with the
checks in them. This option has no effect on other languages.
--vpath=dir : This
option sets the root directory Babel searches first when trying to
load implementation files to preserve splicer block contents in the hand
edited implementation files. If you are generating server-side C for
a concrete class x.y.z and you used --vpath=/tmp, Babel would try to read splicer blocks from
/tmp/x_y_z_Impl.h and /tmp/x_y_z_Impl.c. If it does
not find either file in /tmp, it also checks the current
directory. If you are using --generate-subdirs with --vpath, the
vpath directory is the root of the tree, so for the example, Babel
would search for /tmp/x/y/z_Impl.h and
/tmp/x/y/z_Impl.c. When appropriate, Babel inserts
#line directives to refer debuggers to the original
file. As its name suggests, this option is useful when making vpath
builds using make. Some people also use it to avoid spurious changes
to the files managed by their revision control system.
Table 4.1: Command Line Arguments.
SHORT FORM LONG FORM NOTES -h --helpPrint options to stdout. -v --versionPrint version of Babel. -tform --text=formGenerate text. -clang --client=langGenerate client classes. -slang --server=langGenerate server and client classes. -p --parse-checkOnly check parsing of the SIDL file. --cca-modeNew splicer blocks get CCA-required content. -i --generate-hooksGenerate pre-/post-method hooks. --generate-sidl-stdlibRegenerate the Babel runtime library. -odir --output-directory=dirRoot directory to contain generated files. -g --generate-subdirsGenerate sources in directory tree matching SIDL packaging. --generate-subdirs-offTurn off generate-subdirs. -m --make-prefix=prefixPrepend prefix to names for babel.make. --makefileGenerate a simple GNU Makefile. --multiGenerate multiple targets in a single run. -Rpath --repository-path=pathUse specified XML repository(ies) to resolve symbols. -eregex --exclude=regexDo not generate output for matching symbol(s). --no-default-repositoryDo not use the default repository to resolve symbols. --rename-splicersRename Babel 1.0 splicer blocks to their 1.4 names. --suppress-contractsDon’t generate contract checks in IOR files. --suppress-iorDon’t generate IOR files. --suppress-stubsDon’t generate client-side stub files. --suppress-timestampSuppress time-related metadata generation. --comment-local-onlyReduce doc comments in C stub header. -E --exclude-externalDo not generate code for dependencies. --include-referencedGenerate code for dependencies. -u --hide-gluePut glue code in a subdirectory. --hide-glue-offTurn off hide-glue. -l --language-subdirPut code in a language dependent directory. --language-subdir-offTurn off language-subdir. -x --cxx-ior-exceptionInclude Null IOR checks in C++ Stubs. -V --vpathSet the impl (splicer block) root directory.
So far, we’ve shown described the long forms of command line
arguments, starting with two hyphens “--”.
There are also short forms for many of the more frequently
used commands. See Table 4.1
for details.
To create a new XML version of a SIDL file, use the following command:
% babel -tXML -omydepot mystuff.sidl
To exclude code generation for types whose name begins with “MPI.”, use the following command:
% babel -sC++ –exclude=’^MPI\.’ mystuff.sidl
Now suppose a developer wants to implement a library in C++ that corresponds to these types in the SIDL file.
% babel -E -sC++ mystuff.sidl
Alternatively, the developer could also create C++ implementation files based on the XML repository. In this case, a list of symbols to be implemented would need to be specified. Assuming that all of the types are in a package called “mystuff”, the following command can be issued:
% babel -E -sC++ -Rmydepot mystuff
Now suppose a second developer wants to extend this software. A second SIDL file is created then the implementation files in Fortran 90/95 are generated with the following command:
% babel -E -sf90 -Rmydepot newstuff.sidl
A user now can download both SIDL files and create their Python bindings to use both libraries with the following command:
% babel -cPython -Rhttp://localhost/mystuff/mydepot;
http://www.otherhost.com/newstuff mystuff newstuff
Finally, to generate SIDL files for each package based on the XML stored in the repository, the following command is used:
% babel -tSIDL -Rhttp://localhost/mystuff/mydepot;
http://www.otherhost.com/newstuff mystuff newstuff