Developer Guide for the Ceylan 0.7 version

The intended public for this document is Ceylan developers, i.e. working on the library itself: Ceylan users ought to refer to the Ceylan User Guide.

See the ChangeLog corresponding to this release. Besides this document, Windows users should refer as well to our guide for Windows build.

Build process

General conventions

Not depending on the build platform (i.e. the platform on which the build toolchain will run), Ceylan sources for developers must be retrieved from SVN.

Exception Specifications

Never use exception specifications anymore, and try to remove the ones still existing whenever applicable, i.e. almost everywhere except from some virtual destructors, like the ones inherited from std::exception.

The reason for that choice comes from the fact that C++ exception handling is an epic failure, see 1, 2 for more explanations.

Previous recommendation was to replace all the explicit specifications whenever possible with our exception specification macro CEYLAN_EXCEPTION_SPEC, which was translated into an empty string (the macro was used so that this information would not be lost and could be reverted).

For example, a declaration like void f() throw(MyExceptionType) would have become void f() CEYLAN_EXCEPTION_SPEC(MyExceptionType).

For the sake of readability, we prefer now getting rid both of the throw(XXX) specifications and of CEYLAN_EXCEPTION_SPEC.

The exceptions that can be thrown should only be documented in the function/method comments, with the @throw clause. Note that if no @throw clause is specified, then it means no exception at all is to be thrown.

When building from any non-Windows platform (i.e. UNIX)

If you are performing a native build (not cross-compiling), the Autotools should be used for all UNIX platforms. The build will be then drived by Makefile.am files, and the ones that are generated from them (Makefile.in, Makefile).

If you are cross-compiling, then you should be on GNU/Linux and targeting the Nintendo DS (see our cross-compilation section).

In both cases (native or cross-compilation), for a clean and complete build, one should execute trunk/src/conf/build/autogen.sh, preferably run with the -f (or --full-test) option, as it builds and installs the library, and runs all available tests.

To request a cross-compilation targeting the Nintendo DS, the --nds switch should be added. In this case, to run interactively (i.e. without using autogen.sh) the build system, one could use for example: 

make -f Makefile.cross CROSS_TARGET=nintendo-ds all
Using this kind of alias is quite useful then: 
alias mn='make -f Makefile.cross CROSS_TARGET=nintendo-ds'

For Windows platforms

In that case the fresh SVN sources are expected to be used with the Visual C++ 2008 Express free toolchain.

Cross-compilation to the Nintendo DS

The trunk/src/conf/build/autogen.sh script should be used with the --nds switch. This will pass to configure the relevant --host=arm-nintendo-ds specification and select the cross-compilation tools accordingly. For that the automatically downloaded config.sub is automatically patched to recognize the DS.

A classical preprocessor template to handle the Nintendo DS case is: 

#if CEYLAN_ARCH_NINTENDO_DS
#include "CeylanConfigForNintendoDS.h" // for (ARM9)
#endif // CEYLAN_ARCH_NINTENDO_DS


#if CEYLAN_ARCH_NINTENDO_DS

#ifdef CEYLAN_RUNS_ON_ARM7

	throw ( "Ceylan:: : only available on the ARM9." ) ;

#elif defined(CEYLAN_RUNS_ON_ARM9)


#endif // CEYLAN_RUNS_ON_ARM7


#else // CEYLAN_ARCH_NINTENDO_DS

#endif // CEYLAN_ARCH_NINTENDO_DS

Using SVN (Subversion) for Ceylan

Creating a new Sourceforge SVN repository

Read carefully first the Sourceforge dedicated documentation and the SVN one.

Then:

  1. activate SVN access for the Sourceforge project
  2. wait until the DNS alias is created (ex: ping ceylan.svn.sourceforge.net)
  3. execute svn import ceylan https://ceylan.svn.sourceforge.net/svnroot/ceylan --username=MyUserName where ceylan is a directory containing only one directory, Ceylan, that itself contains the branches, tags, trunk directories

Tools needed to build the Ceylan library on UNIX

Before reporting an error, please check you have upgraded following tools with their latest stable version available:

Rules & good practises

Some developing rules are to be enforced:

  1. no system header mentioned in Ceylan installed headers (hence no system-specific types such as mode_t in our headers): otherwise the API exposed by Ceylan would depend on these system headers, then on a config.h that should be installed to select them but may clash with others, and so on. This implies using opaque handle for forward-declared but undefined struct pointer such as struct ceylan_mode_t ;
  2. all header include guards are designed to not collide with other non-Ceylan headers: for example, HAVE_CTIME is to be replaced by CEYLAN_USES_CTIME
  3. pkg-config should be used whenever available
  4. in each module, public headers should be listed alphabetically (use /bin/ls -1 *.h) in CeylanMODULE_NAMEIncludes.h (ex: CeylanMathsIncludes.h)
  5. no inferior to (<) nor superior to (>) symbols in log messages if not used to specify HTML tags. Otherwise they would be interpreted as mark-up elements. So to delimit precisely strings, prefer using 'A specific message' to <A specific message>
  6. use --consolePlug if you are debugging the file layer, since --classicalPlug would use that layer for logging purpose otherwise. Use this latter classical plug to debug the log system, including the HTML aggregator. Finally, use --HTMLPlug for all other needs
  7. to better understand Locatable referentials, see: test/interface/testCeylanLocatable.cc

Releasing a new Ceylan x.y version

We suppose here that we will create a release for current version and then prepare the setup for the next one.

Release of a Ceylan version

x.y designates here the version to release, which should be the in-development version once stabilized.

  1. freeze the developments on UNIX, ensure all the tests run fine with playTests.sh on UNIX, and check-in everything
  2. optional: enable Automake distribution checking (set do_distcheck=0 in trunk/src/conf/build/autogen.sh) to ensure no distributed file is badly managed (note however that, at least for the moment, this checking cannot fully succeed, because in general tests cannot be configured without distcheck telling where the library was installed)
  3. on Windows, update the check-out, load the previous solution (ex: trunk/src/conf/build/visual-express/Ceylan-x.(y-1).sln), rename it (right-click, still in IDE) with newer version, then do the same for the library in solution (trunk/src/conf/build/visual-express/Ceylan-x.y.vcproj), then save as that library project to a file numbered accordingly, then save all (the full solution) and stop Visual Express, then add these two files to SVN repository and check them in. Rebuild everything and check with cygwin that the test suite runs fine
  4. update, preferably on UNIX, the various version-related files and directories: trunk/src/doc/basic/Ceylan-*-template.txt.in (including Ceylan-NEWS-template.txt.in), trunk/src/doc/web/main/News.html and, in trunk/src/conf/CeylanSettings.inc, CEYLAN_RELEASE_DATE
  5. still from trunk/src/doc/basic, use make effective-changelog-creation html-changelog, under trunk/src/conf/build execute make -f MakeConfigure get-config-scripts, create trunk/src/doc/Ceylan-x.y-release-notes.txt and trunk/src/doc/Ceylan-x.y-changes.txt, etc.
  6. under trunk/src/conf/build, use autogen.sh --chain-test to check everything is still working as expected: all the tests must always succeed, not depending on how many times they are run
  7. create release archives from an already built Ceylan tree: from the trunk, issue make generate-releases, it should create the tar.bez2, tar.gz and zip archives. Build the resulting package on as many other hosts as possible, at least one time on each supported platform. For example, scp ceylan-x.y.tar.bz2 $TOSFCF && sfcf to transfer the archive to Sourceforge's compile farm (if one day it comes back) and to log to their platform chooser
  8. extract each source archive in a separate temporary directory, and check that there are no useless elements (generated files, deprecated content, etc.), and that all files are expected and up-to-date, and that they have the same exact content
  9. regenerate the Sourceforge website, including the Ceylan API (under src/doc, make api toSF)
  10. when satisfied with the result, ensure the version control system is up-to-date with the trunk/src/code/scripts/shell/toci script
  11. create a tag for this new release (ensure you will specify the right UNIX Sourceforge user), for example:
    svn copy https://ceylan.svn.sourceforge.net/svnroot/ceylan/Ceylan/trunk https://ceylan.svn.sourceforge.net/svnroot/ceylan/Ceylan/tags/release-0.7.0 -m "First release of the 0.7 series, with XML parser added and three newly supported platforms: Windows XP, Sun Solaris, OpenBSD."
  12. upload the previously created distribution archives to Sourceforge: select in the admin tab File releases, add a release to the Ceylan package (not the hidden ceylan package), name that release Ceylan-x.y, create it. Upload both release notes and ChangeLog from local tree (respectively from trunk/src/doc/Ceylan-x.y-release-notes.txt and from trunk/ChangeLog). Upload archives thanks to make upload-releases. Add the archives from the web interface (Processor: Platform-Independent), File Type: Source .bz2, Source .gz and Source .zip). Send a notice. Check everything from a non-logged browser.
  13. wait of few hours so that Sourceforge mirrors for file releases are updated, then download all archives, check their content and build and run them with the tests, with build-and-test-package.sh
  14. send a release notice to ceylan-announces@lists.sourceforge.net
  15. write a corresponding news item

Prepare for the next version

Now x'.y' designates the next version.

  1. to prepare the next version/release candidate, one can already update the release numbers for the next version in trunk/src/conf/CeylanSettings.inc: CEYLAN_MAJOR_VERSION and/or CEYLAN_MINOR_VERSION and/or CEYLAN_RELEASE, and in trunk/src/code/CeylanConfigForWindows.h. Create a new trunk/src/conf/build/ceylan-x'.y'.pc.in file, possibly from the one of the previous version. Once updated if needed, register it in SVN (svn add ... && svn ci ...)
  2. create, thanks to a copy and a SVN add, a src/doc/web/Ceylan-x'.y' directory
  3. update trunk/src/doc/web/main/documentation/DocMenu.html so that this new version is referenced
  4. update trunk/src/doc/web/main/News.html with the starting date of this new release

Some developing hints

Please react!

If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line!




[Top]

Last update: Monday, January 3, 2011