OpenSBE Manual

OpenSBE is currently hosted at SourceForge, and is available as both Tarball package and CVS source.

Website. http://sourceforge.net/projects/osbe/

CVS Repository. cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/osbe co OpenSBE

OpenSBE is intended as a platform-independent build system that requires no platform changes in Autoconf and Make files. For example, the CXX subsystem equally well supports GCC and Microsoft Visual C++ compilers, so the Autoconf/Make process will run smoothly on both Unix and Windows™ operating systems.

OpenSBE requires the following software to run:

The following matrix identifies operating environments that OpenSBE has been tested with.

Once you obtain the OpenSBE source from CVS, you can create a tarball package similar to that available from the project's official website.

Here is the complete procedure to package OpenSBE.

dir.ac is used to configure files and subdirectories. On each level of the project directories, starting from the topmost project directory, a dir.ac file specifies files and subdirectories that need to be configured. Additionally, dir.ac may contain commands to execute shell statements and set variables.

dir.ac contained directly under the <PROJECT> directory is linked up with configure.ac through an m4_include([dir.ac]) macro invocation. In turn, dir.ac includes all the required files and subdirectories.

The macros used in dir.ac are OSBE_CONFIG_FILE, OSBE_CONFIG_SUBDIR, and OSBE_CONFIG_COMMANDS.

OSBE_CONFIG_FILE. OSBE_CONFIG_FILE([file_name]) is similar (but not equivalent) to Autoconf macro AC_CONFIG_FILES. Here are the differences:

OSBE_CONFIG_SUBDIR. OSBE_CONFIG_SUBDIR([subdir_name]) includes, through an m4_include statement, the dir.ac file located under the specified subdirectory and modifies the macro OSBE_CURRENT_DIR, so it becomes possible for OSBE_CONFIG_FILE to determine the full pathname of a file being configured.

OSBE_CONFIG_COMMANDS. OSBE_CONFIG_COMMANDS([commands], [init-commands]) accepts shell commands to execute at the end of config.status as the first parameter and shell commands to initialize config.status variables from configure variables as the second parameter. The difference from Autoconf's AC_CONFIG_COMMANDS is that the commands are executed in the build directory corresponding to the source directory containing the AC-file that invokes OSBE_CONFIG_COMMANDS. Here is a (not too realistic) example of a dir.ac file:

   OSBE_CONFIG_FILE([SimpleServerTest.sh])

   chmod_options=777
   OSBE_CONFIG_COMMANDS([chmod $chmod_options SimpleServerTest.sh],
                        [chmod_options=$chmod_options])
	  

File configure.ac, traditionally placed directly under the topmost project directory, is the Autoconf's configure.ac. In OpenSBE, configure.ac contains housekeeping code, directives that enable OpenSBE's features and include libraries required for building your project, and may also contain the usual Autoconf directives. However, with OpenSBE, configure.ac does not specify the directories and files to include in the build; this one is the function of dir.ac.

In general, configure.ac will consist of the following items:

An example of a subsystem-specific macro is OSBE_CXX_USE_LIB that makes C and C++ libraries available for use in your project. See Section 5.3.1.1, “OSBE_CXX_USE_LIB Macro” for details.

An OpenSBE Makefile.in includes rulesets specific to a project and defines build dependencies like the traditional Makefiles do. Every OpenSBE subsystem predefines a number of variables that support building relevant code.

In general, there is a Makefile.in in every project directory with source code; it contains build rules specific to that directory's files and subdirectories. Makefile.in is a template; after being processed by OpenSBE and Automake, it translates into a specific Makefile in the build directory.

To use OpenSBE functionality, every Makefile.in must include ruleset Common.pre.rules at the beginning as follows:

include Common.pre.rules
	

See Chapter 5, OpenSBE Reference for specific Makefile.in structures. Read on through the next chapter for examples.

Consider a simple C++ project that has two parts: a shared library (HelloLib) and the application using the library (HelloApp.)

By OpenSBE conventions, the topmost project directory (<PROJECT>) will initially contain top-level files controlling the build procedures (configure.ac, dir.ac, Makefile.in) plus the src subdirectory containing all source code files along with lower-level files dir.ac and Makefile.in.

This project tree reflects the structure and content of our simple project as it may exist in a revision control repository.

Start with analyzing the contents of configure.ac. As you see, besides the standard m4_include and AC_INIT/OSBE_OUTPUT macros, configure.ac contains two instances of OSBE_ENABLE_FEATURE. These are required to include two features of the CXX subsystem, namely CXX/Ex and CXX/So. CXX/Ex is required for building C++ executables, in this case the HelloApp executable; CXX/So is required for building shared libraries, in this case the HelloLib library. Enabling these features makes available the variables and rules that OpenSBE needs to correctly generate Makefiles and a suitable configure script.

Top-level dir.ac, through the use of macros OSBE_CONFIG_FILE and OSBE_CONFIG_SUBDIR, instructs OpenSBE to configure a Makefile and also include dir.ac from the directory src.

Top-level Makefile template, Makefile.in, is minimal: it includes two required rule files (see Section 5.1.1.1, “Direntry.post.rules” and Section 5.1.2, “Common.pre.rules”) and indicates that Make must change to directory src/ and run through the standard routine. Makefile.in uses OpenSBE variable target_directory_list to list project directories which Make must scan.

On to directory src/. src/ contains two subdirectories with actual source code, HelloLib/ and HelloApp/. We need, again, to configure these two directories as we did for src/.

Refer to files src/dir.ac and src/Makefile.in. src/dir.ac is very similar to the top-level dir.ac: it configures a Makefile and also includes respective dir.ac from HelloLib and HelloApp. src/Makefile.in, aside from listing both subdirectories in the value of target_directory_list, also indicates the dependency between the two in the standard Make fashion. According to this declaration, HelloApp depends on HelloLib. This dependency will be reflected in the instantiated Makefiles.

Next in the line, is the directory HelloLib. Pretty straightforward, two C++ modules and a primitive dir.ac that only configures a Makefile. The different part is in src/HelloLib/Makefile.in; it contains inclusion directives for various rule files. First comes the already familiar Common.pre.rules. Since we are building C++ code, we need to include CXX.pre.rules. CXX.pre.rules does not exist during the development stage, so you cannot reference it by a simple name, as in case of Common.pre.rules. Instead, CXX.pre.rules is instantiated by configure; because of this, Makefile.in uses a generalized pathname (a pathname containing variable part) to include this rule file.

Variables sources define, respectively, names of the source C++ modules and the base name of the compiled shared object. We are instructing the system to compile source files Hello1.cpp and Hello2.cpp into a shared library with base name HelloLib. Variable includes lists include directories, relative to <PROJECT>.

Finally, src/HelloLib/Makefile.in includes another generated rule file by its generalized name, So.post.rules. To build a static library, include Ar.post.rules instead.

Now look into src/HelloApp/. Again, source code files, dir.ac and Makefile.in. Using this approach, you can build project hierarchies of any complexity, and you will always have minimal maintenance hassle under every given subdirectory. src/HelloApp/Makefile.in is a good example of a Makefile template intended for building C++ executables. In structure, the file is similar to src/HelloLib/Makefile.in. It includes rule files Common.pre.rules and CXX.pre.rules, and also rule file Ex.post.rules, which instructs the system to build an executable. Ex.post.rules relies on the values of variables sources and target that identify the source code files and the base name of the executable to build.

What about the HelloLib.so.pre.rules business? This one is a rule file generated specifically for HelloLib when HelloLib gets built. You must include HelloLib's pre-rules in order to build HelloApp; in particular, it enables you to include HelloLib's headers as if they were on the search path (see, for example, the source for src/HelloApp/HelloWorld.cpp.) Since pre-rules file is generated automatically, your only worry is to include the file by its generalized name derived from OpenSBE's project tree conventions (more on this later.)

Read through the next section to learn about basic build steps and OpenSBE's policy on project deliverables.

Assuming we have a sample project tree from the previous section, how do we proceed with preparing the project for distribution and building it on a target system? Instructions below refer to our simple C++ project, but you are free to try them on the C++ sample project included in the OpenSBE distribution.

For OpenSBE, preparing a project tree for building is known as bootstrapping. When you bootstrap a project, OpenSBE generates all the files required to build the project and also creates the configure script under the <PROJECT> directory. This process eliminates all dependencies on Autoconf and OpenSBE and, therefore, prepares the project for redistribution. You can package <PROJECT> for redistribution immediately after bootstrapping.

To bootstrap a project:

In this state, the project is ready for building on any system that Autotools support.

To build a bootstrapped project:

To complete acquaintance with creating multitarget projects, please refer to <PREFIX>/share/OpenSBE/samples/Sample_01, where PREFIX is the OpenSBE installation directory.

Policy on Deliverables. OpenSBE separates source code from intermediate object files and project deliverables, such as the executables in the last example. Instead of creating everything in the project source directories, it replicates the project directory structure under a build directory and builds there. The above instructions invoke configure and make all directory <PROJECT>build/ for this reason exactly. You should prefer this approach over building directly in <PROJECT/>. Here is the filesystem tree of our simple C++ project after bootstrapping and building minus some operation-related files such as Autoconf-related files, Makefiles, and configuration files.

The main intent of the conventional Autoconf-generated configure scripts is to compute variables and instantiate template files (usually Makefiles and header files) by substituting variable values instead of @VARNAME@ entries in templates. configure computes variable values by performing target system tests or, alternatively, by obtaining them from the execution environment.

OpenSBE provides two more ways of defining variable values: through user interaction and through configuration files. Every OpenSBE feature brings in a number of variables; some of the variables are read-only and some are adjustable by end user. OpenSBE computes the default variable values and the user running configure has an opportunity to edit or confirm each of the values.

The order of the default variable values search is this:

OpenSBE-generated configure scripts have two operation modes: the interactive mode, when configure tries to resolve paths and settings by prompting for user input, and the non-interactive mode, when configure tries to deduce all required settings on its own. When configure runs successfully, it creates a configuration file containing values for all required settings; you can reuse the file to rerun configure in non-interactive mode. By default, configure saves the settings in current.config. The following OpenSBE-specific command-line options are available for configure.

--enable-no-questions={yes|no}. Runs configure in non-interactive mode. If configure is unable to figure out at least one parameter, it will terminate with an error. The default is --enable-no-questions=no.

--with-config-file={config file name|no}. Instructs configure to look for default values in the file specified. If you don't specify a file, configure will look for file default.config in the current directory. If you specify --with-config-file=no, configure will ignore the configuration file when search for default values. If you do specify a file and the file is not found, configure will behave the same as if --with-config-file=no were specified.

--enable-guess-location={yes|no}. Instructs configure to guess location of third-party software components required by the application being configured. The default is --enable-guess-location=yes. Usually, configure guesses root directories of libraries used in compilation by matching file hierarchies and file contents under library roots, which can vary from release to release, as well as can differ when debug version is built. The only disadvantage of this option being enabled is that the configure script execution time increases, and the increase can be quite significant when directories /usr and /opt where the search is performed by default contain deep hierarchies or mount points to remote filesystems. To change the default search directory list, update the value of variable LOCATION_GUESS_PATH by setting it in configure.ac as a project developer or/and exporting it outside configure script as an end user.

      export LOCATION_GUESS_PATH="~/mylibs" && ./configure
	    

You can disable the search for root directories as the most time-consuming task, but still let configure guess the structures of libraries. To do this, set LOCATION_GUESS_PATH to an empty string.

Let's complicate our simple C++ project by making use of Xerces library (Xerces.) To include an external library into our project, we need to modify some of the project files. Refer to this modified project tree.

First, we introduced the macro OSBE_CXX_USE_LIB into <PROJECT>/configure.ac. You can learn the details of using the macro in Section 5.3.1.1, “OSBE_CXX_USE_LIB Macro”.

Second, we modified the file <PROJECT/src/HelloApp/Makefile.in> to make Xerces visible to application HelloApp during the build. To that end, we included the rule file Xerces.pre.rules by its generalized name.

The last thing to do was include a relevant Xerces header in HelloWorld.cpp.

To sum up, we used OSBE_CXX_USE_LIB to inform OpenSBE that we are going to need Xerces-related rule files and variables, then linked the Xerces rule file into an appropriate Makefile template. This allowed us to use Xerces code in our project without worrying about linking and compilation issues.

Note that libraries are linked to targets in the order in which they appear in a Makefile. So when library "A" links library "B", Makefile.in should look like this:

# Makefile.in
...
include $(osbe_builddir)/config/CXX/A.pre.rules
include $(osbe_builddir)/config/CXX/B.pre.rules
...
	

For another example of OSBE_CXX_USE_LIB usage refer to <PREFIX>/share/OpenSBE/tests/Test_02, where PREFIX is the OpenSBE installation directory.

There is an easier way to rule libraries dependencies, especially convinient for inter-project libraries usage. This section describes def files format and usage. You also can refer to <PREFIX>/share/OpenSBE/tests/Test_03, where PREFIX is the OpenSBE installation directory. In effect this is Test_02 converted to use def files technology.

Def file is a library definiton file. Its name is a library identificator (refer to the first parameter of OSBE_CXX_USE_LIB macro). It must provide information about library itself and the libraries it uses. Therefore it consists of two virtual parts: library description and dependencies description. In fact it is a shell script and there are no strict rules of order or format of data provided.

Library description is a set of shell variables providing arguments to OSBE_CXX_USE_LIB macro.

As far as def file is a shell script you can provide find function bodies right in place.

Example 4.8.1. OpenSSL.def

name="OpenSSL library"
include=include
lib=lib
so_files="ssl crypto"

The above code is nearly equivalent to the following macro

Example 4.8.2. configure.ac

OSBE_CXX_USE_LIB([OpenSSL],
                 [OpenSSL library],
                 [include],
                 [lib],
                 [ssl crypto],
                 [],
                 [External/OpenSSL.pre.rules])

The second part of def file is a set of osbe_cxx_dep functions calls. The only argument it takes is a library identificator of dependable library

For example, alternative def file for OpenSSL library can look like this

Example 4.8.3. Crypto.def

name="Crypto library"
include=include
lib=lib
so_files=crypto

Example 4.8.3. OpenSSL.def

name="OpenSSL library"
include=include
lib=lib
so_files=ssl

osbe_cxx_dep Crypto

Similarly use can write def files for your in-project libraries

Example 4.8.4. WebLayer.def

name="Common Web Communication Layer (secure/insecure)"
so_files=CommonWebLayer

osbe_cxx_dep OpenSSL
osbe_cxx_dep AnotherInProjectLibrary
osbe_cxx_dep YetAnotherOne

OSBE project libraries cannot be both shared and static (and both so_files and ar_files cannot be used for in-project libraries). Therefore this def file describes shared in-project library with library id equal to WebLayer and target CommonWebLayer. It requires OpenSSL and (via OpenSSL) Crypto, two in-project libraries are also required. To allow OSBE to use that def file you must use OSBE_CXX_USE_DEF macro in your dir.ac file.

Provided with this information OSBE allows you not to fill most of Makefile.in you need for your library. For example, the following Makefile.in

Example 4.8.5. Makefile.in

@weblayer_deps@

sources := WebLayer1.cpp WebLayer2.cpp

@weblayer_post@

will be expanded to

Example 4.8.6. Makefile

include Common.pre.rules
include $(osbe_builddir)/config/CXX/CXX.pre.rules
include $(osbe_builddir)/config/CXX/External/OpenSSL.pre.rules
include $(top_builddir)/config/some/path/to/AnotherInProjectLibrary.so.pre.rules
include $(top_builddir)/config/some/path/to/YetAnotherOne.inl.pre.rules

libname := WebLayer
target := CommonWebLayer

sources := WebLayer1.cpp WebLayer2.cpp

include $(osbe_builddir)/config/CXX/So.post.rules

Note: paths to in-project libraries and their types are determined by OSBE automatically. You just need to inform OSBE about them with OSBE_CXX_USE_DEF macro. By default def files for external libraries are searched in <PROJECT>/defs/ and /usr/share/OpenSBE/defs/ directories. Alternatively you can use OSBE_DEFS environment variable or cxx.def.path variable in default.config. Anyway you can edit this value during configuration process.

Similarly you can attach CORBA, XSDTree and XSDParser.

Example 4.8.7. CorbaXSD.def

name="Corba and XSD library"
so_files=CorbaXSDMix

osbe_cxx_feature_dep CORBA
osbe_cxx_feature_dep XSDTree

Example 4.8.8. Makefile.in

@corbaxsd_deps@

sources := CorbaXSD1.cpp
corba_skeleton_idls := CorbaXSD2.idl
xsd_files := CorbaXSD3.xsd

@corbaxsd_post@

The result is

Example 4.8.9. Makefile

include Common.pre.rules
include $(osbe_builddir)/config/CXX/CXX.pre.rules
include $(osbe_builddir)/config/CXX/Corba.pre.rules
include $(osbe_builddir)/config/CXX/XML/XSD.pre.rules

libname := CorbaXSD
target := CorbaXSDMix

sources := CorbaXSD1.cpp
corba_skeleton_idls := CorbaXSD2.idl
xsd_files := CorbaXSD3.xsd

include $(osbe_builddir)/config/CXX/XML/XSDTree.post.rules
include $(osbe_builddir)/config/CXX/Corba.post.rules
include $(osbe_builddir)/config/CXX/So.post.rules

Of course, such dependancy way can be used for executable files also. Just skip the first part of the file and list dependencies. But you are still forced to mention target in your Makefile.in because no information about it is stored in the def file

This approach allows you to use your project libraries in other projects easily as well. Just specify that something requires WebLayer and dependencies of WebLayer (OpenSSL, Crypto, AnotherInProjectLibrary, YetAnotherOne and even their dependencies) will be resolved automatically composing correct list of include and library directories and files.

Note that it is not "completely another way" to solve dependency problems but just an extention of the previous. For example you can combine both of the approaches. Test_03 has executable named EX11 using direct dependency scheme in completely converted test.

In this section, we transform our simple C++ application into a C++/CORBA application. Refer to this C++ CORBA application reduced tree.

The first change is in configure.ac, to support building CORBA applications, you must enable the CXX/Corba feature. To that end, we added the macro OSBE_ENABLE_FEATURE([CXX/Corba]) into configure.ac.

The new files introduced for their CORBA-related functionality are <PROJECT>/src/HelloLib/HelloLib.idl, <PROJECT>/src/HelloApp/HelloServer.idl, <PROJECT>/src/HelloApp/HelloServerImpl.hpp, and <PROJECT>/src/HelloApp/HelloServerImpl.cpp.

Note how <PROJECT>/src/HelloLib/Hello1.hpp include a CORBA stub that does not even exist during development using angle brackets in the #include directive. This is possible because HelloLib's Makefile.in defines variable corba_includes to point to a correct build-time directory (src). See corba_includes for more information on this variable. In a similar fashion, <PROJECT>/src/HelloApp/HelloServer.idl can reference HelloLib/HelloLib.idl (corba_idl_includes); and <PROJECT>/src/HelloApp/HelloServerImpl.hpp can reference HelloLib/HelloLib.hpp because HelloApp/Makefile.in includes the rule file $(top_builddir)/config/src/HelloLib/HelloLib.so.pre.rules. Another instance of corba_includes, this time in HelloApp/Makefile.in, allows <PROJECT>/src/HelloApp/HelloServerImpl.hpp to include a skeleton header, HelloApp/HelloServer_s.hpp.

If you look into <PROJECT>/src/HelloLib/Makefile.in and <PROJECT>/src/HelloApp/Makefile.in, you can see that we added the necessary CORBA-specific pre- and post-rules files references. We also identified CORBA stub and skeleton files by defining variables specific to CXX/CORBA feature: corba_stub_idls and corba_skeleton_idls. One last thing to do was add the implementation module HelloServerImpl.cpp to the list of sources in HelloApp's Makefile.in.

To complete acquaintance with creating C++/CORBA projects, please refer to <PREFIX>/share/OpenSBE/samples/Sample_02, where PREFIX is the OpenSBE installation directory. Use Section 5.3.7, “CXX/Corba Feature” as the reference.

This section will tell how to add support of XSD mapping to the application.

There are two ways a specific xsd file can be translated into C++ code: DOM and SAX. While the first loads xml file into the memory as a composition of objects, the second notifies you about the elements during the parse process. OSBE allows you to use both of them in your projects.

Firstly change confiure.ac file enabling CXX/XML/XSD feature. Addition of macro OSVE_ENABLE_FEATURE([CXX/XML/XSD]) makes it.

Then for every Makefile you're using for xsd translation you must choose one of two ways of translation. If you want to use DOM style you will need to include $(osbe_builddir)/config/CXX/XML/XSDTree.post.rules file in your Makefile. If SAX style is more preferred please include $(osbe_builddir)/config/CXX/XML/XSDTree.post.rules file.

Files to be processed are required to be mentioned in xsd_files variable in your Makefile. The source files to be compiled will be automatically added to sources variable, there is no need to mention them explicitly.

If you need to use the path to the generated C++ header files you may need to use xsd_includes variable.

OpenSBE's subsystem Documentation/Doxygen support generation of reference code documentation during the builds. Refer to this doxygenated version of our simple C++ project.

We enabled the Documentation/Doxygen feature in configure.ac, created a separate directory for Doxygen configuration files, <PROJECT>/doc/, and modified the top-level dir.ac to include the documentation directory into the project.

You can issue doxygen -g ./Doxyfile.in command to instantiate a Doxygen configuration file, then edit the file to introduce @top_srcdir@ variable which is up to configure to define.

For a more practical example of using Documentation/Doxygen, see the samples that come with OpenSBE.

Let's assume we want to modify the previous Makefile to make it work independently of presence of OSBE_ENABLE_FEATURE([CmdDep]) in our configure.ac file. We should use a list of supplied autoconf substitutes in order to make translation of Makefile.in into Makefile for both of our cases.

Makefile.in with Command Depend's substitutes

    include Common.pre.rules

    chapters := chapter1.txt chapter2.txt chapter3.txt

    .PHONY: all

    all: book.txt

    @CD_TB@book.txt@CD_TE@: $(chapters)
        @CD_CB@
        @CD_LB@ -@echo "Chapters: " $(chapters) @CD_LE@
        @CD_LB@ @cat @(chapters) >$@ @CD_LE@
        @CD_CE@

Note: that each line with a command starts with tab character.

For details of usage you can look into CXX.mk.in file, for example