Difference between revisions of "CrossWire:Sandbox"

From CrossWire Bible Society
Jump to: navigation, search
Line 12: Line 12:
 
==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.
 +
 
 +
""NOTE: This process includes making Internet connections to crosswire.org, to download source code and a sample SWORD module.""
  
 
==Introduction==
 
==Introduction==
Line 18: Line 20:
 
There are four main steps involved:
 
There are four main steps involved:
  
−
* Install all the necessary software packages
+
* Installing all the necessary software packages
−
* Download the latest development SWORD source code
+
* Downloading the latest development SWORD source code
−
* Compile and install SWORD
+
* Compiling and installing SWORD
−
* Test your new SWORD installation is working
+
* Testing that the new SWORD installation is basically working
  
−
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.  The scripts uses sudo to become root when necessary, see below for details on that.
+
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 sudo to become root when necessary, see below for more details on that.
  
 
===Debian===
 
===Debian===
−
 
+
<pre>
 +
#!/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 https://crosswire.org/svn/sword/trunk sword
 +
cd sword
 +
./autogen.sh && ./usrinst.sh && make && sudo make install && sudo make install_config
 +
</pre>
 
===Fedora 10===
 
===Fedora 10===
  
Line 37: Line 48:
 
===Ubuntu===
 
===Ubuntu===
  
 +
==Test script==
 +
 +
The is a very basic test; in particular it does not check indexed search functions at all.
 +
 +
<pre>
 +
#!/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
 +
installmgr -l
 +
diatheke -b KJV -k Jn 3:16
 +
</pre>
  
 
==Becoming root (using sudo)==
 
==Becoming root (using sudo)==
Line 50: Line 76:
 
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.
  
−
==Install necessary software packages==
+
==Installing necessary software packages==
  
−
Starting from a default fairly minimal Linux installation, you need to add a C++ compiler and several other libraries and tools to your system so that you can correctly compile SWORD.  The command to do this 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:
  
 
;Fedora, Red Hat Enterprise Linux, CentOS: sudo yum install <list of packages>
 
;Fedora, Red Hat Enterprise Linux, CentOS: sudo yum install <list of packages>
Line 58: Line 84:
 
;Mandriva: sudo urpmi <list of packages>
 
;Mandriva: sudo urpmi <list of packages>
  
−
These tools will automatically install additional dependent packges, so the ones you request will work.
+
These packaging tools will automatically install additional dependent packages, so the ones you request will work once installed.
  
−
Package names vary too, but you will generally need:
+
Package names vary too, but generally the following packages must be installed:
  
−
* subversion (a tool for obtaining the latest SWORD source code, see below)
+
* subversion (a tool used to obtain the latest SWORD source code, see below)
 
* the GNU C++ compiler, often in a package named g++ or gcc-c++
 
* the GNU C++ compiler, often in a package named g++ or gcc-c++
 
* make
 
* make
Line 86: Line 112:
 
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.
  
−
==Test your 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:
Line 103: Line 129:
 
</pre>
 
</pre>
  
−
If that displays a bunch of text and then something very similar to:
+
If that displays a bunch of text, and then something very similar to:
 
<pre>
 
<pre>
 
John 3:16:  
 
John 3:16:  
Line 112: Line 138:
 
</pre>
 
</pre>
  
−
you have successfully installed a basically working SWORD library and its utilities onto your machine.
+
then the SWORD installation is basically working.

Revision as of 05:23, 3 September 2009

Feel free to edit this page to practice your Wiki skills. You might also consider clicking on your name at the top (if you've already created an account and logged in) to edit your personal pages. It's a good place to practice and might develop into something useful.

Please note, we don't look at this page to answer questions. If you want help please see our Frequently Asked Questions (FAQ) and if that does not help then Contact Us.


Edit your new stuff immediately below this line

Getting Started Compiling and Installing SWORD from Source

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.

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

Introduction

There are four main steps involved:

  • Installing all the necessary software packages
  • Downloading the latest development SWORD source code
  • Compiling and installing SWORD
  • Testing that the new SWORD installation is basically working

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

#!/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 https://crosswire.org/svn/sword/trunk sword
cd sword
./autogen.sh && ./usrinst.sh && make && sudo make install && sudo make install_config

Fedora 10

Fedora 11

Mandriva

Ubuntu

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
installmgr -l
diatheke -b KJV -k Jn 3:16

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

  • 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).
  • Ue the command 
    visudo
    to edit the sudo configuration file.
  • Add a line 
    yourusername ALL=(ALL) ALL
    to the file, save the change and and exit your text editor.
After that, you should be able to type 
sudo id
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

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:

  • subversion (a tool used to obtain the latest SWORD source code, see below)
  • the GNU C++ compiler, often in a package named g++ or gcc-c++
  • make
  • libtool
  • icu
  • zlib-devel (sometimes named zlib1g-dev)
  • clucene-core-devel (sometimes named libclucene-dev)
  • libicu-devel (sometimes named libicu-dev)
  • libcurl-devel (named libcurl4-gnutls-dev on Debian-derived systems)

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

Download the SWORD source code

The single command 
svn https://crosswire.org/sword/svn/trunk sword
will download the current development code of SWORD, into a directory called sword. If it asks you about the SSL key, type p (for permanent, so it remembers the key) and press Enterm and it will continue. Once the command finishes, you should be able to do 
cd sword
and look at all the source code you just downloaded.

Compile and install SWORD

You can read the INSTALL file for the details, but if all is well, after cd sword (so you are inside the SWORD source code directory) you can do 
./autogen.sh && ./usrinst.sh && make
to configure and compile SWORD.

If this fails, make sure you have all the necessary packages installed on your system, and after that, ask for help in the Crosswire forums at http://crosswire.org/forums/ .

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.

Retrieved from "https://wiki.crosswire.org/index.php?title=CrossWire:Sandbox&oldid=6709"