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
Babel requires exactly one of the following
mutually exclusive arguments on the command line unless you use the
--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.
--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
--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
--short-file-name : When the
--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
--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
--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
--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
--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.
SHORT FORM LONG FORM NOTES -h
Print options to stdout. -v
Print version of Babel. -tform
Generate text. -clang
Generate client classes. -slang
Generate server and client classes. -p
Only check parsing of the SIDL file.
New splicer blocks get CCA-required content. -i
Generate pre-/post-method hooks.
Regenerate the Babel runtime library. -odir
Root directory to contain generated files. -g
Generate sources in directory tree matching SIDL packaging.
Turn off generate-subdirs. -m
Prepend prefix to names for babel.make.
Generate a simple GNU Makefile.
Generate multiple targets in a single run. -Rpath
Use specified XML repository(ies) to resolve symbols. -eregex
Do not generate output for matching symbol(s).
Do not use the default repository to resolve symbols.
Rename Babel 1.0 splicer blocks to their 1.4 names.
Don’t generate contract checks in IOR files.
Don’t generate IOR files.
Don’t generate client-side stub files.
Suppress time-related metadata generation.
Reduce doc comments in C stub header. -E
Do not generate code for dependencies.
Generate code for dependencies. -u
Put glue code in a subdirectory.
Turn off hide-glue. -l
Put code in a language dependent directory.
Turn off language-subdir. -x
Include Null IOR checks in C++ Stubs. -V
Set 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
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