Tutorial:Compiling & Installing SWORD

From CrossWire Bible Society

(Difference between revisions)
Jump to: navigation, search
m (Installing necessary software packages: layout)
(See also: * International Components for Unicode (ICU) * CMake for SWORD – experimental * Bindings for SWORD)
(19 intermediate revisions not shown)
Line 1: Line 1:
-
==Getting Started Compiling and Installing SWORD from Source==
+
==Aims==
-
===Aims===
+
This page is intended to help anyone who needs to get started obtaining and compiling the very latest SWORD source code, and then installing and testing it on their machine, on a Linux (or possibly other Unix-like) operating system.
-
This page is intended to help anyone who needs to get started obtaining and compiling the very latest SWORD source code, and then installing and testing it on their machine, on a Linux (or possibly other Unix-like) operating system.
+
For Windows users, refer to [[Tutorial:Compiling & Installing SWORD on Windows]].
''NOTE: This process includes making Internet connections to crosswire.org, to download SWORD source code and a sample SWORD module.''
''NOTE: This process includes making Internet connections to crosswire.org, to download SWORD source code and a sample SWORD module.''
-
===Introduction===
+
==Introduction==
There are four main steps involved:
There are four main steps involved:
Line 18: Line 18:
All of these can be scripted for a specific Linux distribution, and some sample scripts are provided below.  An explanation of each step is also provided, in case you want to understand what the script does (!), or there is no script for your particular Linux distribution.   
All of these can be scripted for a specific Linux distribution, and some sample scripts are provided below.  An explanation of each step is also provided, in case you want to understand what the script does (!), or there is no script for your particular Linux distribution.   
-
===Scripts for some Linux distributions===
+
==Scripts for some Linux distributions==
The bash scripts below use [http://en.wikipedia.org/wiki/Sudo sudo] to become root when necessary, see below for more details on that.
The bash scripts below use [http://en.wikipedia.org/wiki/Sudo sudo] to become root when necessary, see below for more details on that.
-
====Debian or Ubuntu====
+
===Debian or Ubuntu===
'''Note that official SWORD packages exist, please only use this script if you truly need to compile from source, and do NOT have the packaged version of SWORD installed.'''
'''Note that official SWORD packages exist, please only use this script if you truly need to compile from source, and do NOT have the packaged version of SWORD installed.'''
Line 28: Line 28:
<pre>
<pre>
#!/bin/bash                                                                                                                 
#!/bin/bash                                                                                                                 
-
PKGS="subversion build-essential autotools-dev pkg-config libz-dev libclucene-dev libicu-dev libcurl4-gnutls--dev"
+
PKGS="subversion build-essential autotools-dev pkg-config libz-dev libclucene-dev libicu-dev libcurl4-gnutls-dev"
sudo apt-get install $PKGS -y
sudo apt-get install $PKGS -y
svn co http://crosswire.org/svn/sword/trunk sword
svn co http://crosswire.org/svn/sword/trunk sword
cd sword
cd sword
-
./autogen.sh && ./usrinst.sh && make && sudo make install && sudo make install_config
+
./autogen.sh && ./usrinst.sh --enable-shared && make && sudo make install && sudo make install_config
</pre>
</pre>
-
====Fedora 10 or Fedora 11====
+
===Fedora 10 or Fedora 11===
 +
 
 +
'''Note that official SWORD packages exist, please only use this script if you truly need to compile from source, and do NOT have the packaged version of SWORD installed.'''
 +
 
<pre>
<pre>
#!/bin/bash
#!/bin/bash
Line 42: Line 45:
svn co http://crosswire.org/svn/sword/trunk sword
svn co http://crosswire.org/svn/sword/trunk sword
cd sword
cd sword
-
./autogen.sh && ./usrinst.sh && make && sudo make install && sudo make install_config
+
./autogen.sh && ./usrinst.sh --enable-shared && make && sudo make install && sudo make install_config
</pre>
</pre>
-
====Mandriva====
+
===Mandriva===
<pre>
<pre>
#!/bin/bash
#!/bin/bash
Line 52: Line 55:
svn co http://crosswire.org/svn/sword/trunk sword
svn co http://crosswire.org/svn/sword/trunk sword
cd sword
cd sword
-
./autogen.sh && ./usrinst.sh && make && sudo make install && sudo make install_config
+
./autogen.sh && ./usrinst.sh --enable-shared && make && sudo make install && sudo make install_config
</pre>
</pre>
-
====Red Hat Enterprise Linux or CentOS====
+
===Red Hat Enterprise Linux or CentOS===
-
Note this script lacks the '''libcluccene-devel''' library package, because apparently RHEL and CentOS 5.x do not supply one.  This means you must manually download, compile and install '''clucene''' before running this script, to get a SWORD library capable of creating and searching clucene indexes.
+
'''Official Packages now exist. Please use these if possible.''' They will be available soon in the https://fedoraproject.org/wiki/EPEL package repository. Until then, they will be available here:
 +
    http://kojipkgs.fedoraproject.org/packages/sword/1.6.0/1.el5/
 +
    http://kojipkgs.fedoraproject.org/packages/clucene/0.9.21b/1.el5/
 +
 
 +
Note this script is a little more complex than most, because RHEL 5.x and CentOS 5.x lack the '''cluccene-core-devel''' library package.  This means the script must manually download a source RPM package, rebuild it and install it, before it can work with the SWORD source code.  And before it can do that, it has to make sure there is an appropriate setup for building RPMs from source in place.
<pre>
<pre>
#!/bin/bash
#!/bin/bash
-
PKGS="subversion gcc-c++ make libtool icu zlib-devel clucene-core-devel libicu-devel libcurl-devel"
+
PKGS="subversion gcc-c++ make libtool icu zlib-devel libicu-devel libcurl-devel findutils rpm-build"
sudo yum install $PKGS -y
sudo yum install $PKGS -y
 +
if [ ! -f ~/.rpmmacros ]; then
 +
  cat >>~/.rpmmacros <<EOF
 +
%_topdir        ~/rpm
 +
%_tmppath      %{_topdir}/tmp
 +
EOF
 +
  mkdir -p ~/rpm/{BUILD,SOURCES,SPECS,SRPMS,tmp} ~/rpm/RPMS/{athlon,i386,i486,i586,i686,noarch}
 +
fi
 +
rpmbuild --rebuild http://download.fedora.redhat.com/pub/fedora/linux/releases/10/Fedora/source/SRPMS/clucene-0.9.21-1.fc10.src.rpm
 +
sudo rpm -Uvh `find ~/rpm/RPMS/ -type f -name "*clucene*rpm" ! -name "*-debuginfo*"`
svn co http://crosswire.org/svn/sword/trunk sword
svn co http://crosswire.org/svn/sword/trunk sword
cd sword
cd sword
-
./autogen.sh && ./usrinst.sh && make && sudo make install && sudo make install_config
+
./autogen.sh && ./usrinst.sh --enable-shared && make && sudo make install && sudo make install_config
</pre>
</pre>
-
===Test script===
+
==Test script==
The is a very basic test; in particular it does not check indexed search functions at all.
The is a very basic test; in particular it does not check indexed search functions at all.
Line 80: Line 96:
echo yes |installmgr -r CrossWire
echo yes |installmgr -r CrossWire
echo yes |installmgr -ri CrossWire KJV
echo yes |installmgr -ri CrossWire KJV
 +
unset SWORD_PATH
installmgr -l
installmgr -l
diatheke -b KJV -k Jn 3:16
diatheke -b KJV -k Jn 3:16
</pre>
</pre>
 +
This test script should output (after a lot of debugging information):
 +
<pre>
 +
John 3:16:
 +
For God so loved the world, that he gave his only begotten Son,
 +
that whosoever believeth in him should not perish, but have everlasting life.
-
===Becoming root (using sudo)===
+
(KJV)
 +
</pre>
 +
 
 +
==Becoming root (using sudo)==
In order to install software (including installing SWORD itself), you will need to be able to temporarily "become" root.
In order to install software (including installing SWORD itself), you will need to be able to temporarily "become" root.
Line 90: Line 115:
Most Linux (and several *BSD) distributions include a tool called sudo than can do this very conveniently, once set up, without having to repeatedly enter a root password.  On some Linux distributions (including Ubuntu) this is already set up for you during the installation process.  On others, you will need to
Most Linux (and several *BSD) distributions include a tool called sudo than can do this very conveniently, once set up, without having to repeatedly enter a root password.  On some Linux distributions (including Ubuntu) this is already set up for you during the installation process.  On others, you will need to
-
* Become root (i.e. obtain a root comamnd shell) in some other way (log in as root, or use su, and type in the root password when prompted for it).
+
* Become root (i.e. obtain a root command shell) in some other way (log in as root, or use su, and type in the root password when prompted for it).
-
* Ue the command <pre>visudo</pre> to edit the sudo configuration file.
+
* Use the command <pre>visudo</pre> to edit the sudo configuration file.
* Add a line <pre>yourusername ALL=(ALL) ALL</pre> to the file, save the change and and exit your text editor.
* Add a line <pre>yourusername ALL=(ALL) ALL</pre> to the file, save the change and and exit your text editor.
-
After that, you should be able to type <pre>sudo id</pre> to run the (harmless) command id as root.  sudo will prompt you for your own password, but if it is used more than once within a short period, will "remember" that you have already provided it and not ask for it again.  This is very convenient.
+
* After that, you should be able to type <pre>sudo id</pre> to run the (harmless) command id as root.  sudo will prompt you for your own password, but if it is used more than once within a short period, will "remember" that you have already provided it and not ask for it again.  This is very convenient.
-
===Installing necessary software packages===
+
==Installing necessary software packages==
Starting from a fairly minimal Linux installation, a C++ compiler and several other libraries and tools must be added to the system before compiling SWORD.  These come in packages. The command to install packages varies between different Linux distributions.  A few examples follow:
Starting from a fairly minimal Linux installation, a C++ compiler and several other libraries and tools must be added to the system before compiling SWORD.  These come in packages. The command to install packages varies between different Linux distributions.  A few examples follow:
Line 123: Line 148:
These will generally automatically "pull in" other necessary packages such as binutils, automake and autoconf as dependencies.
These will generally automatically "pull in" other necessary packages such as binutils, automake and autoconf as dependencies.
-
===Downloading the SWORD source code===
+
==Downloading the SWORD source code==
-
The single command <pre>svn http://crosswire.org/sword/svn/trunk sword</pre> will download the current development code of SWORD, into a directory called sword.  Once the command finishes, you should be able to do <pre>cd sword</pre> and look at all the source code you just downloaded.
+
The single command <pre>svn co http://crosswire.org/svn/sword/trunk sword</pre> will download the current development code of SWORD, into a directory called sword.  Once the command finishes, you should be able to do <pre>cd sword</pre> and look at all the source code you just downloaded.
-
===Compiling and installing SWORD===
+
==Compiling and installing SWORD==
-
The INSTALL file contains all the details, but if all is well, after cd sword (i.e., from inside the SWORD source code directory) the command line <pre>./autogen.sh && ./usrinst.sh && make</pre> to configure and compile SWORD.   
+
The INSTALL file contains all the details, but if all is well, after cd sword (i.e., from inside the SWORD source code directory) the command line <pre>./autogen.sh && ./usrinst.sh --enable-shared && make</pre> to configure and compile SWORD.   
If this fails, make sure all the necessary packages are installed on your system, and after that, please ask for help in the [http://crosswire.org/forums/ Crosswire forums] or on the sword-devel mailing list.
If this fails, make sure all the necessary packages are installed on your system, and after that, please ask for help in the [http://crosswire.org/forums/ Crosswire forums] or on the sword-devel mailing list.
Line 135: Line 160:
To install SWORD, after successfully compiling SWORD, you can do <pre>sudo make install && sudo make install_config</pre> to install SWORD and a default configuration file on your machine.
To install SWORD, after successfully compiling SWORD, you can do <pre>sudo make install && sudo make install_config</pre> to install SWORD and a default configuration file on your machine.
-
===Testing a new SWORD installation===
+
==Testing a new SWORD installation==
As a very basic test, you can download and install the KJV SWORD "module" and then check that the command line bible reader diatheke can read a verse from it.    The commands to do this (using the usual bash shell) are:
As a very basic test, you can download and install the KJV SWORD "module" and then check that the command line bible reader diatheke can read a verse from it.    The commands to do this (using the usual bash shell) are:
<pre>
<pre>
-
 
export SWORD_PATH=~/.sword
export SWORD_PATH=~/.sword
mkdir -p $SWORD_PATH/mods.d
mkdir -p $SWORD_PATH/mods.d
Line 162: Line 186:
then the SWORD installation is basically working.
then the SWORD installation is basically working.
 +
 +
== See also ==
 +
* [[DevTools:ICU|International Components for Unicode (ICU)]]
 +
* [[DevTools:CMake|CMake]] for SWORD &ndash; experimental
 +
* [[DevTools:Bindings|Bindings]] for SWORD
 +
 +
[[Category:Tutorials]]

Revision as of 11:28, 11 June 2013

Contents

Aims

This page is intended to help anyone who needs to get started obtaining and compiling the very latest SWORD source code, and then installing and testing it on their machine, on a Linux (or possibly other Unix-like) operating system.

For Windows users, refer to Tutorial:Compiling & Installing SWORD on Windows.

NOTE: This process includes making Internet connections to crosswire.org, to download SWORD source code and a sample SWORD module.

Introduction

There are four main steps involved:

All of these can be scripted for a specific Linux distribution, and some sample scripts are provided below. An explanation of each step is also provided, in case you want to understand what the script does (!), or there is no script for your particular Linux distribution.

Scripts for some Linux distributions

The bash scripts below use sudo to become root when necessary, see below for more details on that.

Debian or Ubuntu

Note that official SWORD packages exist, please only use this script if you truly need to compile from source, and do NOT have the packaged version of SWORD installed.

#!/bin/bash                                                                                                                 
PKGS="subversion build-essential autotools-dev pkg-config libz-dev libclucene-dev libicu-dev libcurl4-gnutls-dev"
sudo apt-get install $PKGS -y
svn co http://crosswire.org/svn/sword/trunk sword
cd sword
./autogen.sh && ./usrinst.sh --enable-shared && make && sudo make install && sudo make install_config

Fedora 10 or Fedora 11

Note that official SWORD packages exist, please only use this script if you truly need to compile from source, and do NOT have the packaged version of SWORD installed.

#!/bin/bash
PKGS="subversion gcc-c++ make libtool icu zlib-devel clucene-core-devel libicu-devel libcurl-devel"
sudo yum install $PKGS -y
svn co http://crosswire.org/svn/sword/trunk sword
cd sword
./autogen.sh && ./usrinst.sh --enable-shared && make && sudo make install && sudo make install_config

Mandriva

#!/bin/bash
PKGS="colorsvn gcc-c++ make libtool icu zlib1-devel libclucene-devel libicu-devel libcurl-devel automake"
sudo urpmi $PKGS
svn co http://crosswire.org/svn/sword/trunk sword
cd sword
./autogen.sh && ./usrinst.sh --enable-shared && make && sudo make install && sudo make install_config

Red Hat Enterprise Linux or CentOS

Official Packages now exist. Please use these if possible. They will be available soon in the https://fedoraproject.org/wiki/EPEL package repository. Until then, they will be available here:

   http://kojipkgs.fedoraproject.org/packages/sword/1.6.0/1.el5/
   http://kojipkgs.fedoraproject.org/packages/clucene/0.9.21b/1.el5/

Note this script is a little more complex than most, because RHEL 5.x and CentOS 5.x lack the cluccene-core-devel library package. This means the script must manually download a source RPM package, rebuild it and install it, before it can work with the SWORD source code. And before it can do that, it has to make sure there is an appropriate setup for building RPMs from source in place.

#!/bin/bash
PKGS="subversion gcc-c++ make libtool icu zlib-devel libicu-devel libcurl-devel findutils rpm-build"
sudo yum install $PKGS -y
if [ ! -f ~/.rpmmacros ]; then
  cat >>~/.rpmmacros <<EOF
%_topdir        ~/rpm
%_tmppath       %{_topdir}/tmp
EOF
  mkdir -p ~/rpm/{BUILD,SOURCES,SPECS,SRPMS,tmp} ~/rpm/RPMS/{athlon,i386,i486,i586,i686,noarch}
fi
rpmbuild --rebuild http://download.fedora.redhat.com/pub/fedora/linux/releases/10/Fedora/source/SRPMS/clucene-0.9.21-1.fc10.src.rpm
sudo rpm -Uvh `find ~/rpm/RPMS/ -type f -name "*clucene*rpm" ! -name "*-debuginfo*"`
svn co http://crosswire.org/svn/sword/trunk sword
cd sword
./autogen.sh && ./usrinst.sh --enable-shared && make && sudo make install && sudo make install_config

Test script

The is a very basic test; in particular it does not check indexed search functions at all.

#!/bin/bash
export SWORD_PATH=~/.sword
mkdir -p $SWORD_PATH/mods.d
echo yes |installmgr -init
echo yes |installmgr -sc
echo yes |installmgr -r CrossWire
echo yes |installmgr -ri CrossWire KJV
unset SWORD_PATH
installmgr -l
diatheke -b KJV -k Jn 3:16

This test script should output (after a lot of debugging information):

John 3:16: 
For God so loved the world, that he gave his only begotten Son, 
that whosoever believeth in him should not perish, but have everlasting life.

(KJV)

Becoming root (using sudo)

In order to install software (including installing SWORD itself), you will need to be able to temporarily "become" root.

Most Linux (and several *BSD) distributions include a tool called sudo than can do this very conveniently, once set up, without having to repeatedly enter a root password. On some Linux distributions (including Ubuntu) this is already set up for you during the installation process. On others, you will need to

Installing necessary software packages

Starting from a fairly minimal Linux installation, a C++ compiler and several other libraries and tools must be added to the system before compiling SWORD. These come in packages. The command to install packages varies between different Linux distributions. A few examples follow:

Fedora, Red Hat Enterprise Linux, CentOS
sudo yum install <list of packages>
Debian, Ubuntu, Mint
sudo apt-get install <list of packages>
Mandriva
sudo urpmi <list of packages>

These packaging tools will automatically install additional dependent packages, so the ones you request will work once installed.

Package names vary too, but generally the following packages must be installed:

These will generally automatically "pull in" other necessary packages such as binutils, automake and autoconf as dependencies.

Downloading the SWORD source code

The single command
svn co http://crosswire.org/svn/sword/trunk sword
will download the current development code of SWORD, into a directory called sword. Once the command finishes, you should be able to do
cd sword
and look at all the source code you just downloaded.

Compiling and installing SWORD

The INSTALL file contains all the details, but if all is well, after cd sword (i.e., from inside the SWORD source code directory) the command line
./autogen.sh && ./usrinst.sh --enable-shared && make
to configure and compile SWORD.

If this fails, make sure all the necessary packages are installed on your system, and after that, please ask for help in the Crosswire forums or on the sword-devel mailing list.

To install SWORD, after successfully compiling SWORD, you can do
sudo make install && sudo make install_config
to install SWORD and a default configuration file on your machine.

Testing a new SWORD installation

As a very basic test, you can download and install the KJV SWORD "module" and then check that the command line bible reader diatheke can read a verse from it. The commands to do this (using the usual bash shell) are:

export SWORD_PATH=~/.sword
mkdir -p $SWORD_PATH/mods.d

echo yes |installmgr -init
echo yes |installmgr -sc
echo yes |installmgr -r CrossWire
echo yes |installmgr -ri CrossWire KJV
installmgr -l
diatheke -b KJV -k Jn 3:16

If that displays a bunch of text, and then something very similar to:

John 3:16: 
For God so loved the world, that he gave his only begotten Son, 
that whosoever believeth in him should not perish, but have everlasting life.

(KJV)

then the SWORD installation is basically working.

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Miscellaneous
Toolbox