DevTools:CMake

From CrossWire Bible Society

Revision as of 03:15, 23 June 2013 by Osk (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

An initial, experimental, proof-of-concept version of a CMake build system for the SWORD library is under way borrowing from the BibleTime CMake system and others. The current pumpkin holder for it is Greg Hellings.



Contents

Where is the code?

Currently the source for the CMake build system can be found in the regular SWORD SVN tree and is included with distributions starting with version 1.6.2.

Now what do I do with the code?

Now that you have the code, hopefully in a relatively clean build environment so you can test it without colliding with already installed versions of the SWORD library, it's time to give building a try. Elsewhere you can find documentation on the list of libraries which are optionally a part of SWORD, so I won't go over installing those optional dependencies here - use your favorite method/package manager to install them.

Obviously, since this is all about CMake, you'll be required to install CMake. You can get pre-built binaries here: [1]. There are versions for Linux/Unix, OS X, Windows, SunOS/Sparc, IRIX64, HPUX and AIX. Most of them have GUIs, but can also be run from the command line. If you are in Linux/Unix there is almost certainly a package available from your system. I have tested the build with versions 2.6.4 and 2.8 of CMake - if you have something from the 2.4 series and are feeling brave enough to try it, please edit the file CMakeLists.txt and, near the top of the file, change the line that reads CMAKE_MINIMUM_REQUIRED(VERSION 2.6.0) to require a version low enough so you can test with your version. I have set the minimum at 2.6.0 because that is the minimum I have tested with and not because I am aware of any limitations of versions earlier than 2.4 which would break the system. Please report any success or failures you have as a result of changes.

If you have the SWORD supporting libraries you want to use installed, and also have CMake installed, it is now time to try to configure the system. Follow the appropriate steps laid out below:

Bash or other command-line tool, probably Unix/Linux environment

An example of building in a subdir, shared library, setting the prefix, and building the python bindings:

mkdir cmakebuild
cd cmakebuild
cmake ../ -DLIBSWORD_LIBRARY_TYPE="Shared" -DCMAKE_INSTALL_PREFIX="/usr" -DSWORD_BINDINGS="Python"
make -j4
sudo make install

GUI users

For those of you using the GUI interfaces with, for example, Windows or OS X or even the CMake GUIs for Linux:

iPhone

There are special steps to be taken to build for the iPhone, if you so wish. When I next get on my Mac, I will post these directions especially for you.

How can I customize my options?

While not all of the options and functionality of the original SWORD automake system are necessarily supported, I would like to document those which I know about and their status. Also, I want to document the basic method of specifying these options.

CMake Options

Probably the only important CMake option for normal users is the "Generator" option. For those of you using a GUI, you will be prompted for the Generator to use the first time you click Configure. For command-line users, the default will generally be Unix Makefiles - this goes for Linux, Mac OS X and MinGW in my experience - (possibly different if you're using the DOS prompt in Windows, I haven't checked there) unless you specify otherwise. To get a list of the generators supported by your version of CMake run "cmake --help". The generators will be listed at the bottom. Select the one you would like, for example Xcode, and add the option string: -G Xcode to your invocation of CMake. Other examples might be -G "KDevelop3 - Unix Makefiles" if you wanted to use KDevelop3 but have it managing Unix Makefiles.

SWORD Options

For all of these options if you are using a GUI, you can set these options by clicking "Add Entry" before configuring and setting the Name and Value fields. For command line users, you would set an option named SWORD_OPTION to value VALUE by adding -DSWORD_OPTION=VALUE to your CMake options. This would look like cmake -DSWORD_OPTION=VALUE ../cmake_build or similar.

The options are listed here by name, grouped roughly by their functioning.

General, interesting options

Optional dependencies

Developer or Packager specific options

How do I hack the code?

If you want to directly hack the SWORD library for reasons other than CMake, I suggest you go elsewhere on this wiki for that.

If you have suggestions and edits for this system, you are welcome to create patches and submit them to the sword-devel mailing list. Also, you can find my email on the list's archives and send them directly to me (Greg Hellings) or, if you are ambitious, you are welcome to create a branch using your favorite DVCS and publish it somewhere and let me know. I am familiar with at least bzr and git and can pull your branch if that is how you would prefer to contribute.

For a basic overview - all of the files are contained within the sword/cmake directory except for a few CMakeLists.txt files in strategic locations. CMakeLists.txt is the file that is the entry point for the system. Any calls to functions like FIND(ICU QUIET) will look for a module either included with your CMake system (ZLib) or included within the directory specified by the line SET(CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") CMake will try to find a file titled FindICU.cmake in one of those paths to satisfy your call to FIND(ICU).

Source lists are in sword/cmake/sources.cmake. I have kept them broken out evenly into their separate base directories under sword/src. Additionally any sources which are only included for conditional reasons have their own set of variables down towards the bottom of that file with what are hopefully successfully mnemonic names.

After calls to FIND(<library>), the system then has to react to which files were found and which were not. This is handled with some semi-complicated logic in sword/cmake/muxsources.cmake.

Since utilities, tests, bindings and examples are all optional compilations, they have their own CMakeLists.txt files located in their own directories. These are invoked with a call to ADD_SUBDIRECTORY([path to directory]). Additional CMakeLists.txt files could also be created for things like the bindings and other self-contained paths.

After build, install is handled in the sword/cmake/install.cmake file.

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Miscellaneous
Toolbox