BuildingBibleTime

This page describes how to build BibleTime. This is meant for those who want to develop BibleTime or just want to build it from source.

Contents 1 Linux/Unix 1.1 Prerequisites for building BibleTime 1.1.1 Tools 1.1.2 Library dependencies 1.2 Building BibleTime 1.2.1 Getting the code 1.2.2 The build script 1.2.3 Manual cmake 1.2.4 After the first build 1.3 Troubleshooting 1.4 IDEs 1.4.1 KDevelop 1.4.2 Qt Creator 2 Windows 3 Mac OS X

Linux/Unix

Prerequisites for building BibleTime

It's important to have all prerequisites/dependencies installed before trying to build, otherwise you may get strange errors. The build tool doesn't always give informative messages.

Tools

• g++ (not just gcc) or clang++
• cmake (autotools are NOT needed! cmake takes care of everything)
• make (e.g. GNU Make)
• git client for getting the latest source code (we also have tarballs for releases, so git is not necessary for those)
• Qt4 development tools (uic, moc etc.) - probably bundled with the Qt development package

Library dependencies

If you need to build something yourself remember the dependencies - most of the problems when building for example Sword come from lacking dependencies (clucene, icu...). The easiest way is to install the SWORD and Qt binary and development packages with your system's package manager, that should take care of almost everything else including their tool and library dependencies.

• zlib compression library (lib64z1-dev)
• sword library binary
• sword library development package (headers)
• clucene library binary
• clucene library development package (headers)
• Qt4 library binaries and development packages (headers) with at least the following Qt components present:
  • QtCore
  • QtDbus
  • QtGui
  • QtNetwork
  • QtWebKit
  • QtXml
• Boost library (may depend on platform whether it's divided into library and dev package(s))
• sword may require these:
  • libcurl
  • icu

Again, for all libraries: remember that you have to have both binaries and development headers installed! Many distos have binary packages and -dev or -devel packages for them; for example libqt and libtq-dev. And don't forget dependencies!

Building BibleTime

Here's how to build the development version of BibleTime:

Getting the code

• Go to a directory where the bibletime/ base directory may be created
• "git clone git://gitorious.org/bibletime/bibletime.git" - to check out the latest source code
• "cd bibletime"

The build script

• run "./build*.sh" (build-debug.sh, build-release.sh)
• build*.sh runs "make install" automatically.
  • For debug build there will be a bibletime binary in build/install/bin/, release build installs into /usr/local/. Debug build is recommended if you want a safe and easy install.

Manual cmake

If build*.sh fails or if you want to do it manually:

• Create a build directory and cd into it
• run "cmake -D MODE=DEBUG .." (see the build scripts for the MODE), or...
• for interactive frontend: "ccmake -D MODE=DEBUG .."
  • Basic usage of ccmake: press c, check and possibly edit the variables. Press c again for another round until you see the option to 'generate and exit'. Press 'g'.
  • If there are errors: 'e' to exit help after the process errors, then on the list of variables move down to erroneous variable, hit enter to input the correct value, then enter again.
• If you need to hack further you can look at and edit CMakeCache.txt and run cmake again.
• There will be makefiles in the ./build/ directory. Run "make" there to build BibleTime. Run "make install" to install it. Install location depends on the MODE (see above and read the build script).

After the first build

• The source directory will not be touched or modified in any way. All the files made by the build process will be in the build/ directory. You can run "make" or "make install" there again.
• The list of files to be build is in cmake/bibletime_source_list.cmake. New source files will be added there.
• When something is changed or edited you have to run make or even cmake again:
  • If CMakeLists.txt file in bibletime dir has been changed, running make should be enough; it re-runs cmake automatically.
  • If files have been added/removed to/from the source tree and bibletime_source_list.cmake, running make should be enough.
  • If the underlying system (libraries, tools etc.) has been radically changed you have to delete CMakeCache.txt file from build dir and run cmake or the build script again.
  • Sometimes it may be useful to delete the whole build directory and start from scratch.

• After running cmake once you can build the project with KDevelop (see the instructions below)

Troubleshooting

• Did you remember all prerequisites? Most of the build problems (with any project, not only BibleTime) come from lacking dependencies, either tools, binaries or development headers.
• Distro packagers don't notice all bugs, there might be something wrong with cmake files of Qt or some other library or tool so that all files are not found.
  • "No rule to make target `/usr/lib/libICE.so', needed by `bibletime'" is an example from real life for two previous items. There seemed to be some bug in some Kubuntu 8.04 package which caused some X11 related development libraries not being installed automatically as a dependency. The -dev libraries had to be installed manually. Additionally the make system error description is exceptionally misleading.
• If compiling fails with a message about something missing or a needed library (for example "libpcre"), you may have to install that library (binary and development headers). See the previous item for an example.
• CMakeLists.txt file in bibletime directory includes some custom cmake files which are in cmake/ directory. Look at them if the build system doesn't find clucene or sword.
• If the linking phase fails check if you have the requested library installed but having no .so link. For example if the linker complains about the missing -lphonon library, it's possible that you have libphonon.so.4 but not libphonon.so link (this is a real example from the Kubuntu 8.04).
• You can ask help in bt-devel email list or possibly in the Discussion page of this page.

IDEs

KDevelop

You can create a project for BibleTime:

• Project->Import existing project
• Directory: your bibletime directory
• Generic C++ application (custom buildsystem)
• OK

...and the project is created. Now you have to change some project options:

• Project->Project Options
• Build Options -> Run the build tool in...
  • Put here the build/ directory which is under the bibletime/ directory by default

Now you can use Build->Build Project or Build->Install, but only after you have run cmake from the command line once (see the instructions above).

Qt Creator

The following instructions should work for Qt Creator 2.1 RC and later.

• Open the CMakeLists.txt file of the project
• A wizard dialog opens, and first asks you for a location to place build files in. If the folder does not exist, create it. Click the "Next >" button at the bottom of he dialog.
• The next page of the wizard asks for cmake arguments
  • For a debug build, use "-D CMAKE_BUILD_TYPE=Debug" and for a release build, use "-D CMAKE_BUILD_TYPE=Release". You may also append " -D CMAKE_INSTALL_PREFIX="install/"" to tell CMake that "make install" should install into the "install" directory under the build location, otherwise "make install" attempts to install BibleTime system-wide, but may fail due to access permissions.
  • Click the "Run CMake" button
  • It should now run and the last message is: "- Build files have been written to:..."
  • Close the wizard by clicking the "Finish" button.
• Switch to the "Projects" view (CTRL+5)
  • OPTIONAL STEP: In "Build Settings" under "Build Steps" is a box which says "Make: make". Click the "Details" button next to the box. In the "Additional arguments" box, type "-j#" where # is the number of CPU cores on your computer + 1. This makes compilation faster by utilizing all available CPU cores by running # jobs in parallel. The additional +1 job is to utilize the a CPU core which sits idle in case another compilation jobs waits for I/O requests to complete.
  • In "Run Settings" add a new deploy configuration with a new Make build step. Put "install" as an additional argument to that Make step. You can also rename the new deploy configuration "make install" or anything else you like.
• Under main window "Build" menu, click "Run" (CTRL+R). This makes Qt Creator try to build and run BibleTime. It should successfully build BibleTime, but fail to run it properly. To see compilation progress, click "Compile Output" (ALT+4) from the bottom of Qt Creator.
• After Qt Creator has failed to run BibleTime in the last step, go back to the "Projects" view "Run Settings" page.
  • add a new Run configuration ("Custom executable")
  • Leave the fields as they are, it's easier to fill them later
• Make Qt Creator try to run ("Build->Run", CTRL+R) BibleTime again. After a short while, Qt Creator opens a dialog asking for the custom executable (because you didn't give it in the new Run configuration).
  • Browse and add "bin/bibletime" from the install location as the executable
  • OPTIONAL STEP: It is recommended to add "--debug" to the arguments field.
  • Accept the dialog by clicking "Ok".

If all went well, then BibleTime should start and you have successfully configured Qt Creator to work with your copy of the BibleTime source code. :)

Windows

There are some directions at Building_on_Windows

Mac OS X

Building on Mac is relatively straight-forward.

• Install MacPorts: http://www.macports.org.
• Use MacPorts to install qt4-mac.
• Use MacPorts to install curl, clucene, zlib, icu, etc with their development packages and any other dependencies that SWORD has as well as cmake and boost for BibleTime.
  • icu is actually not used by BT and SWORD can be compiled without it.
• Manually install the SWORD library from the source tarball, probably to a location like /opt/manual, so it's not mixed in with the system headers, but is instead in a directory parallel to MacPorts in /opt/local.
• Download the Bibletime source and build the debug version, then run. Everything should work out properly. Complain on the list if it doesn't, I'll figure out what steps I missed here, and everything will be fine in the end.

Problems with Mac build

• It does not find any of the modules that either MacSword or BibleDesktop install. These both install to ~/Library/Application Source/Sword. (This is a biggie!!!) -- Testing now with SWORD HEAD and seeing if that works better for DM. (Greg)
• IMHO, the layout does not at all look like a Mac application. It should have a Mac look and feel. Especially since the download is 38M. That is pretty big for a the Bible programs available on the Mac. Some of it has a Mac look and feel (e.g. tabs) but much of it doesn't (the same can probably be said of BibleDesktop). (Acceptance by Mac users will determine whether this is a big deal.)
  • It should be possible to reduce the download size; Windows package is only ~11MB including msvc files. The look&feel is harder. Probably we aren't going to change the UI greatly just because of Mac. Qt does what it does to look and behave like a Mac UI and it's not always enough. MacSword is highly recommended for those who want a native app. BibleTime may be good for those who want to use one app on many platforms or need some specific feature. --Eelik 12:27, 10 November 2009 (UTC)
• There shouldn't be both a Preferences menu selection and a Settings menu. The Settings menu should go away. Many Mac users won't expect that.
  • But BibleTime users on multiple platforms will. It's about choice, and if you are choosing BibleTime, it's not for a MAC Look and feel,it's for a BibleTime Look and Feel. If you change it to match the MAC, then it's not BibleTime any more. BibleTime has a distinctly Qt Look and Feel, because that is what it is designed around, and mainly what makes the interface so nice, I have used more than 20 sword based projects, and my favourite is BibleTIme for it's presentation, customizable layout, menu structure, and book shelf manager. Changing these to look more "MAC" ish, detracts from these features which are built around Qt. --ntrcessor 01:01, 12 March 2010 (CST)