[PREVIOUS] [HOME] [NEXT]

Install the package

Assuming your system meets the requirements outlined in the Introduction, the next step is to unpack the database files and make the database. In your $HOME directory unpack the tar ball using the following command:

	tar -xvzf baghdad_atlas.tgz

All associated subfolders and files will unpack into the master directory BaghdadAtlas. The source codes necessary to generate the SQL database will be located in their own directory: $HOME/BaghdadAtlas/src. The source data csv files are located in $HOME/BaghdadAtlas/CSV_DATA. See here for brief details concerning the organization of the BaghdadAtlas directory tree structure.

A Makefile is provided to build the SQL database and help with the installation process. The Makefile will automatically detect the OS (Linux of Mac OS X only; Windows-based environments/emulators are not currently supported) and Python version running on the host machine and define the make variables accordingly. This will hopefully negate the necessity for any manual edits to the top-level Makefile. To compile and install the required software, invoke the command-line operations outlined below:

	cd ~/BaghdadAtlas/src   # assuming tar ball was unpacked in the home directory 
	make                    # build the C extension-functions library
	make run                # build the SQLite database
	make install            # install library and database into specified locations

The first command compiles the extension-functions.c code into a dynamic shared-object library providing enhanced mathematical functionality (trigonometric functions, square root, power, logarithmic methods etc.) not readily available with standard SQLite3 engines. The next make run command is issued to run the appropriate Python scripts to define the OS-dependent library in the SQL scripts provided in ~/BaghdadAtlas/sql_codes, and create the Python-version-dependent SQL database. This stage may take a few minutes to compile the data depending on your OS. Finally, the make install instruction installs:

The new C library (Linux: libsqlitefunctions.so, Mac OS X: libsqlitefunctions.dylib) into the ~/BaghdadAtlas/UDF/sqlite-amalgamation directory. This is the specified location for extension functions to be loaded into SQL scripts. Make sure the path and library are correctly defined for your OS in all SQL scripts inside the ~/BaghdadAtlas/sql_codes folder that use the load_extension() method.
The SQL database (Python 2: atlas_baghdad_py2.db, Python 3: atlas_baghdad_py3.db) into the ~/BaghdadAtlas/notebook_analysis and ~/BaghdadAtlas/sql_codes directories. The IPython Notebook and SQL scripts are ran from within these locations.

For MAC OS X users, additional flags may need to be defined during the make process. If the compilation fails, and SQLite3 was installed through MacPorts, define (i.e. enable/uncomment):

	MACPORTS = /opt/local
	CPPFLAGS = -I$(MACPORTS)/include
	LDFLAGS = -L$(MACPORTS)/lib -lsqlite3

Or, if SQLite was installed using Fink, define:

	FINK = /sw
	CPPFLAGS = -I$(FINK)/include
	LDFLAGS = -L$(FINK)/lib -lsqlite3

Now try to recompile using the following rule to make the target:

	$(CC) $(CFLAGS) $(CCFLAGS) $(CPPFLAGS) $(OBJECTS) -o $@ $(LDFLAGS)

Clean-up operations can be performed to remove C, Python, and SQLite artifacts in addition to objects created with the Jupyter Notebook. For more information execute the command make help:

   default
       Compile shared-object library to enhance SQLite functionality.
   run
       Run script on local machine to create SQLite ATLAS.
   install
       Install shared-object library to location:
                       BaghdadAtlas/UDF/sqlite-amalgamation
       Install SQLite database to the following two locations:
                       BaghdadAtlas/sql_codes
                       BaghdadAtlas/notebook_analysis
   clean
       Remove C artifacts.
   clean-pyc
       Remove Python artifacts.
   clean-sql
       Remove SQLite artifacts.
   clean-nb
       Remove artifacts and objects created with Jupyter Notebook.
   clean-all
       Remove all C, Python, SQLite artifacts and Jupyter Notebook objects.

Organization

After unpacking and installation, your filesystem should have the following structure:

~/BaghdadAtlas/book/ ⇒ Contains a pdf of the ATLAS and a summary document.
~/BaghdadAtlas/CSV_DATA/ ⇒ Contains the source csv data files used to compile the database.
~/BaghdadAtlas/document/ ⇒ Contains the html manual.
~/BaghdadAtlas/notebook_analysis/ ⇒ Contains a Jupyter Notebook illustrating various methods for interacting with the data; after compilation the SQL database (Python 2: atlas_baghdad_py2.db, Python 3: atlas_baghdad_py3.db) is also installed into this location. A few brief comments are given in cells explaining database queries.
~/BaghdadAtlas/sql_codes/ ⇒ Contains several SQL scripts illustrating methods for interacting with the data; after compilation the SQL database is also installed into this location. A few brief comments are given above the transaction in each of the example SQL scripts explaining the query.
~/BaghdadAtlas/src/ ⇒ Contains the source code used to create the database and extension modules.
~/BaghdadAtlas/UDF/ ⇒ Directory created after compilation of the sqlite extension-functions library; contains the subfolder sqlite-amalgamation into which the sqlite extension-functions library (Linux: libsqlitefunctions.so, Mac OS X: libsqlitefunctions.dylib) is installed.