[asterisk-scf-dev] Major build system update

[Kevin P. Fleming]

On Monday afternoon I merged a significant set of improvements to the 
Asterisk SCF build system, and along with that there were a number of 
changes in each of the component repositories to take advantage of the 
improvements. This message documents the new features (and caveats) of 
this improved build system:

* The CTest module (from the CMake distribution) is now included as part 
of the build; the effect of this is that there is a BUILD_TESTING 
variable in CMake. It defaults to 'on', but can be turned off, and if 
that is done, none of the unit tests in the tree will be built, which 
can save quite a bit of time.

* The prefix on all the build script functions and variables was changed 
from "asterisk_scf" to "astscf". This was mostly important for the 
variables, as it affects how CMake groups them in its GUI representation.

* A number of functions in AsteriskSCF.cmake are there for use by the 
script itself; they shouldn't be called from CMakeLists.txt files in 
component repositories. These functions now have a double-underscore 
prefix to indicate that they are for internal use.

* The build system defines a C++ preprocessor macro that is used to mark 
functions and classes as being 'exported' from their translation units; 
this is necessary on Windows. Previously this macro was called 
ASTERISK_SCF_ICEBOX_EXPORT, but it is now called ASTSCF_DLL_EXPORT, 
since it was not specific to IceBox services.

* Many functions in AsteriskSCF.cmake now perform sanity checking when 
they are called to ensure that their prerequisites are met.

* Components can now be built from sources in multiple directories, as 
long as astscf_component_init() and one of the astscf_component_build_() 
functions are called from the top-most directory that contains any part 
of the component. Subdirectories that are descended into via 
add_subdirectory() calls *between* the component initialization and 
build functions are free to add C++ sources, C++ headers and Slice files 
to the component.

* Handling of Slice files (translation to C++ headers and sources, 
compilation and linking into components) is now done by defining 
'collections', using astscf_slice_collection(). This function is 
extensively documented in AsteriskSCF.cmake, but the basics are that a 
'collection' consists of a directory (or tree of directories) containing 
Slice files, possibly a directory or directories containing C++ headers 
generated from them, and possibly a library built from C++ sources 
generated from them. Global collections can be referenced by name from 
anywhere in the build system after they are defined; in addition, 
projects will have an automatic 'PROJECT' collection defined if they 
have a top-level 'slice' subdirectory. Installation of Slice files, 
headers and libraries is done by requesting that the collection be 
installed; all other details are taken care of by the build system 
itself. The only downside to this is that when a test or component has a 
Slice file that it uses entirely for internal purposes (i.e. it will not 
be installed on the target system), a collection must still be defined 
to be able to refer to it; this is called a 'local' collection.

* Slice files are now translated and compiled on a per-component basis, 
even if multiple components in the same directory use the same Slice 
file(s).

* If a Makefile-style build system is generated by CMake, the generated 
Makefiles will now provide a 'make uninstall' target.

* When builds are performed using GCC, the build system will now ask the 
linker to ensure that libraries that are built do not have any 
unresolved symbols; this means that such problems will be caught at 
build/link time, instead of not being caught until run time. Such 
problems are typically caused by forgetting to tell the build system 
that a component makes use of an installed library.

* Building on the Slice file collection support above, 
astscf_component_add_slices() will now automatically discover Slice 
files that the component needs as a result of using the one(s) specified 
in the function call, and if any of those also need to be 
translated/compiled for this component, they will be added to the 
component as if the developer had requested them directly. In addition, 
this will happen even for Slice files that have already been translated, 
compiled and linked into a library, if a Slice file from that collection 
is *explicitly* added to a component. In the near future, this will 
allow for component-specific translation of Slice files using the 
soon-to-be-released metadata overlay plugin.

* astscf_build_library() can now accept a SHARED, STATIC or MODULE 
argument to indicate the type of library to be built; 
astscf_set_libtype() has been removed.

* If a project has a top-level 'include' directory, it is no longer 
necessary to explicitly call include_directories() to have it added to 
the search path; astscf_project() will do that automatically.

In addition to these build system changes, a number of component 
repositories had some noticeable changes:

* The library produced by the ice-util-cpp repository is now called 
'astscf-ice-util-cpp'.

* The library produced by the util-cpp repository is now called 
'astscf-util-cpp', and everything in this repository is built into that 
library (as opposed to being built into three or more libraries).

* The library produced by the slice repository is now called 'astscf-api'.

* The CMake build system is no longer brought into a gitall integrated 
build by the gitall-asterisk-scf.sh script; instead, a copy of the build 
system has been incorporated into the gitall repository itself, using 
the git 'subtree' merge mechanism. There is a page on wiki.asterisk.org 
describing how this was done and the steps to be taken to bring updates 
into the gitall repository.

* In a number of project repositories, the directory containing Slice 
definitions for that project was called 'local-slice' or 'local_slice'; 
they are all now called 'slice', and their structure follows that of the 
main slice repository. This resulted in a number of changes to the 
namespaces that various interfaces reside in.

* The Slice definitions in project repositories (which generally define 
replication classes and interfaces, and configuration interfaces) are 
now installed along with the main Asterisk SCF API Slice definitions.

-- 
Kevin P. Fleming
Digium, Inc. | Director of Software Technologies
Jabber: kfleming at digium.com | SIP: kpfleming at digium.com | Skype: kpfleming
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at www.digium.com & www.asterisk.org