Change the default class skeleton
Change the default configure.ac.lib.rpsl
Change the default pc.in file
Change the default Makefile.am file
Set and change library release and shared versions
Set and change a module release version
Specify what libraries a library or executable depends on
Specify compile arguments
Specify compile arguments unique to a particular file
Specify static linking
Force a linker flag order with libtool
Modify a file and rebuild with dependency checking
Perform a fractional build
Clean targets and intermediate files
Reference a 3rd party shared object in a nonstandard location
Reference another project's installed objects
Build a statically-linked library
Build a shared object that links against another object
Build an executable that references objects
Install objects and executables to a specified location
Build in a different tree than the source directory
Avoid recursive make badness
Integrate with an IDE
Change to a different development environment
Use source in a non-standard directory structure
Move a module tree to the group project or global home


Change the default class skeleton. top
Put new ClassName.cpp.rpsl ClassName.h.rpsl TemplateClassName.h.rpsl and 
TemplateClassName.tpl.rpsl files earlier in the skeleton file search order, 
either in directory
   ${RPSL_PROJ}/usr/share/utl for project-wide skeletons or
   ${RPSL_USER}/usr/share/utl for local user skeletons


Change the default configure.ac.lib.rpsl top
Put a new configure.ac.lib.rpsl or configure.ac.exec.rpsl in the module 
top-level directory.  

Run rpslSyncBuild.  


Change the default pc.in file top
Put a new thelibnamever.pc.in.rpsl in the module top-level directory.  See
the default one for how to edit it.  The macro variables (@var@) are available
for replacement but can be omitted for override paths, etc.  The file can have
any variable in the form libdir=varvalue (upper section) but only specific
keywords are allowed such as Name, Description, Requires, etc. as seen in the 
bottom section. 
Then run rpslSyncBuild.


Change the default Makefile.am file top
A custom Makefile.am is supported for a subdirectory in the main source 
directory of a library.  Put a new Makefile.am.lib.sub.rpsl in the subdirectory 
and this will be copied to Makefile.am by RPSL without any modifications.  This 
is a good way to set custom compiler flags, etc. for a particular source file.


Set and change library release and shared versions top
Modify the file rpslParams in the current library top-level directory with
the release and shared version specifications:

     rpslParams:
     release = 1.2.3    major minor micro
     shared = 1:0:1     current revision age

   Then run rpslSyncBuild.


Set and change an executable release version. top
Modify the file rpslParams in the current executable top-level directory 
so that it contains the release version specification:

     rpslParams:
     release = 1.2.3     major minor micro

     (a shared version entry is ignored if present)

   Then run rpslSyncBuild.


Specify what libraries a library or executable depends on. top
Specify the pkg-config configuration with the file rpslParams, in the top 
level module directory with each line representing library name, a relation, 
and a release version.

     rpslParams:
        release = 0.0.0  <--- release version of current library
        shared = 0:1:0   <--- shared version of current library
        foo >= 0.0.0     <--- zero or more dependency lines

   Then run rpslSyncBuild.


Specify compile arguments. top
Set these by changing the defaultcxxflags variable in the runConfigure configure 
runner script in the top-level module directory.

  Then run ./runConfigure

This script also takes flags in the form of an argument that are passed directly 
to configure and override the default flags.  Be careful, however, because doing
this will disable all default flags including the default prefix location.


Specify compile arguments unique to a particular file. top
If a particular source file or set of files requires some non-standard compiler
flags then put them in a separate directory under the main source directory
and run rpslSyncBuild.  This will generate a Makefile.am in that directory. Next,
copy the Makefile.am to Makefile.am.lib.sub.rpsl and modify the CXXFLAGS line.  This
new file will be copied directly back to Makefile.am each time rpslSyncBuild is
run in place of the normal RPSL processing in that subdirectory.  The 
Makefile.am.lib.sub.rpsl will need to be changed manually if any files are added or 
removed from the subdirectory.


Specify static linking. top
RPSL currently builds both static and dynamic libraries on machines
that support shared libraries. In, say, Linux, you will get  the following 
targets installed in usr/local/lib:

libdisplay-0.0.so.1@      libdisplay.a    libdisplay.so@
libdisplay-0.0.so.1.0.0*  libdisplay.la*  

(codes: @=symbolic link, *=executable, otherwise simple binary file.)

Static-only targets will be restricted to:

libdisplay.a  libdisplay.la*  

Static linking is generally better for debugging and faster to compile.

RPSL/autotools compile static and dynamic objects by default, if possible.  
But for static linking only, one can pass the argument --disable-shared 
to configure.  This can be done by editing runConfigure or simply giving
runConfigure this flag as an argument to pass to configure.  

Note that if any arguments are passed to configure via runConfigure then
all default arguments for configure will be disabled.


Force a linker flag order with libtool. top
The processing in libtool likes to reorder linker flags - this can cause
problems when the linker flags need to be in some order.  An example is 
when you want to force the link of a whole library archive.  The way to
do this is to modify the pc.in file Libs: line with a special flag with
no spaces, only commas.  For linux:
-Wl,--whole-archive,base/libbase.a,--no-whole-archive
This will stay together.  Save the file in the local top-level directory
as thelibnamever.pc.in.rpsl and it will override the generic one when you
run rpslSyncBuild.


Perform a fractional build. top
For the case where all module source is in one directory RPSL 
doesn't support this use case. There is only one directory makefile and 
that compiles all source in the directory. For the case were source is 
in its own subdirectory, which is supported by RPSL, building in that 
directory does not require working implementation files elsewhere.  It does 
require that any files that are included by the subdirectory source are valid.


Clean targets and intermediate files. top
The standard commands include make clean (all compiler-generated files in
the build tree) and make uninstall (all installed files in the target tree
such as all includes and libraries, including the pc file in the pkgconfig
directory).


Reference a 3rd party shared object in a nonstandard location. top
This is best avoided and it is recommended that any external libraries 
be housed in a directory "external" under one of the sandbox directories 
and configured to install targets into that sandbox usr target location, 
including the pkgconfig pc file.  But if necessary it is easy to reference
a library in another location.  Simply edit a pc file as follows with the 
shared object's location and put this pc file in the pkgconfig search path:

prefix=/opt
exec_prefix=/opt
libdir=${exec_prefix}/lib/nonstandard
includedir=${prefix}/include  [include statements are like: <nonstandard/foo.h>]

Name: test
Description: My library.
Version: 4.3.1      
Requires:
Conflicts: 
Libs: -L${libdir} -ltest
Cflags: -I${includedir}/nonstandard


Reference another project's installed objects. top
To share another project's libraries if it is decided not to install them in
the common RPSL_HOME location simply add that project's target pkgconfig 
directory path to the PKG_CONFIG_PATH variable so that the appropriate pc files
will be found.  This is similar to linking with an external library.  The 
secondary project (the one not assigned to RPSL_PROJ) will not be searched for
custom file skeletons, nor will it be a default install target.  It will just
be an additional source of libraries. This scenario is best avoided.


Build a shared object that links against another object. top
RPSL specifies dependencies via the rpslParams file that includes
version requirements. Simply build and install the base object and put its 
name in the rpslParams file with a version range.  For the dependent object,
RPSL will include and link to the first example of the installed base object it 
finds after checking the version requirements. The pc files are found by 
searching the pkgconfig paths in order: RPSL_USER, RPSL_PROJ and RPSL_HOME.  
This can be modified by adding search paths to the PKG_CONFIG_PATH environment 
variable (in your .cshrc, say).


Build an executable that includes and links one or more other objects, zero 
or more of which are static. top
For the case where RPSL/autotools has built both dynamic and static libraries,
the default executable has everything dynamically linked.  The executable can 
be purely statically linked.


Install static and dynamic library objects and executables to a 
specified location. top
This target location prefix is an argument to the call to configure.  There 
is a script file runConfigure in each module's top-level directory that 
runs configure with default settings that can be edited.  The default settings
for target location, however, should not be changed if other RPSL modules 
reference the one in question.


Build in a different tree than the source directory. top
RPSL/autotools supports having different directories for source, build, and 
the installed targets.  It isn't really necessary, however, to have different
source and build trees for development, and normally, once the source tree is 
sync'd, configure would be run in the top level source directory. In any case, 
the configure script in the source tree can be run from any directory. That 
new directory will be populated with makefiles and certain other files, and 
all of the intermediate build result files after running make.


Avoid recursive make badness. top
RPSL supports a main source directory and one additional level of subdirectories.
Currently recursive make is how these subdirectories are made.  Automake can
support a single Makefile.am in the top directory and this would prevent 
recursive make badness but that's not implemented yet in RPSL.


Integrate with an IDE. top
RPSL/autotools integrates with Eclipse, for example.  Set up a 
tree as a standard make C++ project.  The commands newclass, newtclass and 
rpslSyncBuild can be put into the Run, External Tools button using the properties 
feature.  Add dialog boxes for the class name (string argument) and variables 
for the newclass and rpslSyncBuild working directories (absolute project path).  
The RPSL scripts newclass and newtclass should also trigger a refresh of the 
project so the new files are seen and indexed.


Change to a different development environment. top
RPSL must be told where to look for referenced modules and how to include
and link to them.  Basically, the pc files in the PKG_CONFIG_PATH must contain
the proper locations of the external modules.  Other approaches include 
changing environment variables or soft links.


Apply this build system to source in a non-standard directory structure.  top
RPSL supports one and two directory levels of source code for each 
module. If necessary, the scripts could be modified to recurse additional levels 
and insert Makefile.am's there. This is discouraged.


Move a library in development ($RPSL_USER) to the group project or global 
home tree. top
As a minimum, the target location in runConfigure would be changed.  For 
organizational reasons the module tree should be moved to the new location. 
Then it would be conventional to put the source in the module tree under cvs.

top