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 the build toolchain will run on), Ceylan sources must be retrieved from SVN

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/cross-compilation), for a clean and complete build, one should execute trunk/src/conf/build/autogen.sh, preferably run with the -f / --full-test option, as it builds and installs the library, and performs all available tests.

To request a cross-compilation targeting the Nintendo DS, the --nds switch should be added. 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++ 2005 Express 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.

Classical preprocessor template to handle the Nintendo DS case: 

#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 Sourceforge dedicated documentation and 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, with the previous version, the current version has been setup, hence we will create a release for current version and then prepare the setup for the next one.

Release 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 a distribution with ./autogen.sh --only-prepare-dist: it should produce an archive named trunk/ceylan-x.y.tar.bz2. Another approach is to use an already built Ceylan tree, and from the trunk to issue make dist-bzip2 and make dist (for tar.gz archive). 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 both source archives in separate temporary directories, and check that there are no useless elements (generated files, deprecated content, etc.), and that all files are expected and up-to-date, and 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. create two distribution archives: ceylan-x.y.tar.bz2 thanks to cd trunk/src/conf/build; autogen.sh --only-prepare-dist and ceylan-x.y.tar.gz thanks to make dist from trunk
  13. upload both 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 by anonymous FTP both archives to upload.sourceforge.net in the incoming directory (delete first through the web form any alreay hidden release with the same name). Add the archives from the web interface (Processor: Platform-Independent), File Type: Source .bz2 or Source .gz). Send a notice. Check everything from a non-logged browser.
  14. wait of few hours so that Sourceforge mirrors for file releases are updated, then download both archives, check their content and build and run them with the tests, with build-and-test-package.sh
  15. send a release notice to ceylan-announces@lists.sourceforge.net
  16. 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: Wednesday, March 12, 2008