DevTools:CMake

From CrossWire Bible Society
Revision as of 20:30, 23 February 2010 by Greg.hellings (talk | contribs)

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.


Where is the code?

Currently you can get a copy of the code from Bazaar on Launchpad. If you just want to grab a copy for testing and evaluation, follow these simple steps:

  • Install Bazaar [1] for your system.
  • Checkout the CMake branch. If you want to checkout into the directory cmake_sword execute the following command: bzr branch lp:~greg-hellings/libsword/cmake-port cmake_sword
  • For those of you who are using graphical interfaces, you'll want to find the way in your system to "Branch" a repository. If your Bazaar client doesn't know how to process lp:~greg-hellings/libsword/cmake-port you can try giving it the URL bzr://bazaar.launchpad.net/~greg-hellings/libsword/cmake-port
  • If you have more advanced knowledge of Bazaar and its abilities, you might want to know that lp:libsword/trunk is kept in sync with the official Subversion repository of CrossWire and I keep cmake-port synced with it whenever possible.

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: [2]. 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

  • Create a new directory where the actual configure or build will take place - this can be an empty subdirectory of SWORD (e.g. sword/cmakebuild) or a parallel directory (sword/../swordbuild) or anywhere else you would like. I personally use the parallel directory and following example commands will reflect a directory structure with cmake_sword/ as the base of the SWORD sources and a parallel directory cmake_build/ as the build directory.
  • Change into your build directory: cd cmake_build
  • Issue the call to CMake with any options you want to test and point it to the root of your SWORD sources: cmake <options> ../cmake_sword/
  • Check that there are no error messages and that CMake ends with the messages "Configuring done", "Generating done", and "Build files have been written to: <object directory>"
  • From here on out, building should be just like building with Autotools - 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:

  • Open the CMake GUI.
  • For the line where the GUI asks "Where is the source code:" browse to the directory where you checked out the SWORD source: C:\Users\Greg\Documents\Projects\cmake_sword
  • For the line where the GUI asks "Where to build the binaries:" browse to a directory (does not need to exist yet for the GUI to operate) that is not the same as the path with the source: C:\Users\Greg\Documents\Projects\cmake_build
  • If you wish to specify certain options (see the section on options), click the "Add Entry" button and enter the argument you wish to specify under "Name" and the value of that argument under "Value".
  • Click "Configure"
    • If prompted to create the build directory, say "Yes"
    • Select the "generator" for this project... for this, select the system you wish to use to actually do the compile. Some examples are different versions of Microsoft Visual Studio, Unix Makefiles, MSYS Makefiles, Cygwin Makefiles, Xcode projects, Eclipse projects, Borland projects and more.
    • Unless you are building for the iPhone (in which case you should skip to the section especially for iPhones!), you will probably want to leave "Use default native compilers" unless you are a power user and know what compiler you would like to use. You could use special options here if you need to select special cross-compilers or similar.
  • After configure is completed, if there were errors, you will have a chance to correct them. If certain libraries were not located or you wish to use other values, you can select the Advanced View or check Show Advanced and manually edit any of the cached values.
  • If you are happy with the results and there are no errors or after you have corrected any errors, click Configure a second time.
  • Click Generate
  • Navigate to the directory where you specified to build the binaries and invoke your build system through its native mechanics - open the project file, execute the Makefiles, etc.

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

  • SWORD_GLOBAL_CONF - If this has a non-empty value, then the option "-DGLOBCONFPATH=${SWORD_GLOBAL_CONF}/sword.conf" is passed to the compiler. If SWORD_GLOBAL_CONF is unset or is empty, then no additional options are passed to the compiler. I believe support for this is only half implemented at the moment. I believe that, if this is set, then an actual sword.conf should be written to the directory specified. At present this is not the case. I am unsure of the correct default behavior if this is not specified.
  • SWORD_BUILD_UTILS - If this has the value "No" then utilities will not be built. If this has any other value or is left unspecified, the Utilities will be built and installed.
  • SWORD_BUILD_EXAMPLES - If this is given the value "Yes" then the examples/cmdline demos will be built. If this has any other value or is left blank, then demos will not be built.
  • SWORD_BUILD_TESTS - If this is given the value "Yes" then the SWORD tests will be run. They are still run using the same system as before (or as closely as it could be replicated). If this has any other value or is left unspecified, tests will not be run. The exception to that is the simple buildtest.cpp in the root of the sword/ folder which will always be built when the library is built.

Optional dependencies

  • SWORD_NO_ZLIB and SWORD_USE_INTERNAL_ZLIB - If SWORD_NO_ZLIB has value "Yes" then No ZLib support will be built into the library. If SWORD_NO_ZLIB has any other value, then ZLib support will be built into the library. If support is to be built in, and either a system-wide ZLib is not found OR SWORD_USE_INTERNAL_ZLIB is set to "Yes", then the internal version will be built. If a system library is found AND SWORD_USE_INTERNAL_ZLIB is set to anything other than "Yes" or has no value, then the system library will be linked against. If both SWORD_NO_ZLIB and SWORD_USE_INTERNAL_ZLIB are set to "Yes" then SWORD_NO_ZLIB will be used, and no ZLib support will be built.
  • SWORD_NO_CURL - If this is set to "Yes" then cURL support will not be included regardless of whether cURL is found on the system. If this is any other value or has no value set, then cURL will be built against if it is located and ignored if it cannot be located.
  • SWORD_NO_CLUCENE - If this is set to "Yes" then CLucene will be ignored if found. If this is set to any other value or has no value, then the library will be built against CLucene if it can be located and ignored if it cannot be located.

Developer or Packager specific options

  • LIBSWORD_LIBRARY_TYPE - If this has the value "Shared" then a shared library will be build (DLL or .so) along with the exported linking stub. If this is unspecified, then a static library will be built.
  • CMAKE_BUILD_TYPE - If this is given the value of "Debug" then the default SWORD debugging flags (-g3 -Wall -Werror -O0) will be enabled. If this is unspecified or any value other than "Debug" then the flag -O3 will be enabled.
  • SWORD_ENABLE_WARNINGS - If this has the value "Yes" then -Werror will be passed to the compiler. This would allow independent specification of -Werror without needing to enable actual debugging. Should this also enable -Wall?
  • SWORD_ENABLE_PROFILE - if this has the value of "Yes" then the -pg option will be passed to the compiler. I don't know what this does, but it was available with Autotools, so it has been replicated here. This defaults to off.
  • SWORD_ENABLE_PROFILEN - if this has the value of "Yes" then the "-g -finstrument-functions" options will be passed to the compiler. The same disclaimer goes for this as goes for the previous option. This also defaults to off.
Retrieved from "https://wiki.crosswire.org/index.php?title=DevTools:CMake&oldid=7794"