# Configuring and Building the Storage Manager

## Detailed Description

Configuring and building the storage manager consists of these steps, all done at the root of the distribution directory tree.
• bootstrap
• configure
• build (make)

## Bootstrapping

Bootstrapping might not be necessary, but if you have the autotools installed, it might save time to bootstrap the first time you try to build, particularly if you are installing on a system other than Linux. To bootstrap, type ./bootstrap. You can also look at that script and run selected parts of it, since all it does is run the autotools.

Autotools run abysmally slowly on Solaris.

## Configuring

There are two parts to configuring the storage manager. The original configuration scheme of SHORE was encapsulated in config/shore.def, which described all or most pertinent CPP macros. We are moving away from that scheme and replacing it with autoconf options and features, but a few things still remain under the control of shore.def. These fall into three categories:
• details related to autoconf-controlled options, such as pathnames
• basic compile-time constants that someone extending the storage manager might want to change
• maintainer's tools

There remaining some CPP macros not described in config/shore.def:

• code of occasional utility for debugging purposes
• code intended to be the subject of future experimentation

Configuring amounts to running ./configure from the root of the distribution directory tree, and, depending on the features you wish to use, editing config/shore.def.

Remarks:
The storage manager API contains a method ss_m::config_info (q.v.) that allows a server to determine, at run time, some of the compile-time limits determined by the configuration.

### Configuration Options

To find the configuration options, type
 ./configure --help

, the output of which is reproduced here.

SHORE-specific Features:
certain critical sections.
--enable-lp64         default:yes     Compile to use LP 64 data model
No other data model is supported yet.
But we hope some day to port back to LP32.
--enable-checkrc      default:no      Generate (expensive) code to verify return-code checking
If a w_rc_t is set but not checked with
method is_error(), upon destruction the
w_rc_t will print a message to the effect
"error not checked".
--enable-trace        default:no      Include tracing code
Run-time costly.  Good for debugging
problems that are not timing-dependent.
Use with DEBUG_FLAGS and DEBUG_FILE
environment variables.  See \ref SSMTRACE.
--enable-dbgsymbols   default:no      Turn on debugger symbols
Use this to override what a given
debugging level will normally do.
--enable-explicit     default:no      Compile with explicit templates
NOT TESTED.
\todo mainpage.h compile with or remove explicit templates

--enable-valgrind     default:no      Enable running valgrind run-time behavior
Includes some code for valgrind.
--enable-purify       default:no      Enable build of <prog>.pure
--enable-quantify     default:no      Enable build of <prog>.quant
--enable-purecov      default:no      Enable build of <prog>.purecov

SHORE-specific Optional Packages:
--with-page-size        1024, 2048, 4196, 8192(default), 16384, or 32768
--with-hugetlbfs        Use the hugetlbfs for the buffer pool.
Depending on the target architecture, this might
be useful.  If you use it, you will need to set
a path for your hugetlbfs in config/shore.def.
The default is :
#define HUGETLBFS_PATH "/mnt/huge/SSM-BUFPOOL"
--without-mmap          Do not use mmap for the buffer pool. Trumps
hugetlbfs option.
--with-debug-level1     Include level 1 debug code, optimize.
This includes code in w_assert1 and
#if W_DEBUG_LEVEL > 0 /#endif pairs and
#if W_DEBUG_LEVEL >= 1 /#endif pairs and  and
W_IFDEBUG1
--with-debug-level2     Include level 2 debug code, no optimize.
Equivalent to debug level 1 PLUS
code in w_assert2 and
#if W_DEBUG_LEVEL > 1 /#endif pairs and
#if W_DEBUG_LEVEL >= 2 /#endif pairs and
W_IFDEBUG2
--with-debug-level3     Include level 3 debug code, no optimize.
Equivalent to debug level 2 PLUS
includes code in w_assert3  and
#if W_DEBUG_LEVEL > 2 /#endif pairs and
#if W_DEBUG_LEVEL >= 3 /#endif pairs and
W_IFDEBUG3


Bug:
GNATS 136 Only 64-bit platforms are supported. The issue is that lsns and some other data structures need atomic methods.
Bug:
GNATS 143 The polyphase merge-sort does not handle this case: More than one run is required AND keys are embedded in objects AND the keys are already in lexicographic order in the object AND the keys are properly aligned AND the keys span multiple pages. It returns an error indication about a "broken key" comparison not being implemented. The workaround is to provide a marshal function or to put the sort key in the header of the object or to provide more memory (larger number of pages for the run size) for the sort.
Bug:
GNATS 139 Convert w_assert9 to w_assert3 where the asserts are still reasonable and remove the rest. Some of these are obsolete, some are racy in the new mt-context. All the w_assert9's are what used to be w_assert3; they were turned into 9 to disable them until they could be evaluated for usefulness, and many have been converted to 2 or 3-level asserts; many remain to be addressed.

### Description of Selected CPP Macros

In this section we describe selected macros defined (or not) in config/shore.def.

• USE_SSMTEST Define this if you want to include crash test hooks in your smsh. This is for a maintainer's testing purposes and should not be defined for a release version of the storage manager.

• COMMON_GTID_LENGTH : You can override the default length of a global transaction id. Useful only if your server implements distributed transactions.

• COMMON_SERVER_HANDLE_LENGTH : You can override the default length of a server handle, the handle by which the server identifies a coordinator of distributed transaction. Useful only if your server implements distributed transactions.

• SM_LOG_PARTITIONS : You can override the default maximum number of open partitions for the log by defining this.

• SM_EXTENTSIZE : You can override the default extent size with this. Warning: you must also address the alignment of Pmap_Align4 based on the resulting size of a Pmap. See extent.h, logrec.h, pmap.h. Warning: this has never been tested. This information is included only for those whose hacking on the storage manager who may require larger extents.

### Tcl and smsh

The storage manager test shell, smsh, uses Tcl. Autoconf tries to find Tcl in a standard place; if it is found, fine. But if not, you must define two paths to your Tcl library and include files in Makefile.local at the top of the directory tree. If you Tcl installation is not built for multithreading, you must install such a copy and put its path in Makefile.local.

Tcl is available from

## Building

Building the storage manager consist of running
 make


Since it is not alway easy to tell what options were used for the most recent build in a directory, the compiler options used on the build are put in the file makeflags and the rest of the options are determined in config/shore-config.h, produced at configuration time.

Note:
For Solaris users: if you use CC rather than gcc, you will probably have to run configure with environment variable CXX defined as the path to your CC compiler, and you might also need
 configure --enable-dependency-tracking

.

## Checking the Release

After building the storage manager, you can check it by running
 make check

in the root of the directory tree. This runs unit tests for each libary.

Attention:
The storage manager test shell, smsh, is run by
 make check

. Smsh uses Tcl. The path to you Tcl installation is given in Makefile.local at the top of the directory tree.
Note:
If you do not have Tcl installed and want to test the installation without smsh, you may run make check and ignore the fact that it chokes trying to build smsh, because smsh is the last test that make check runs.

## Installing the Release

You may run
 make install

This installs:
• <includedir> [default: <prefix>/include]
• the libraries in
• <libdir> [default: <exec-prefix>/lib]

To change the prefixes, use one or more of these configure options:

 configure --prefix=\<path\>

or
 configure --libdir=\<path\>

or
 configure --includedir=\<path\>


## Functions

static rc_t ss_m::config_info (sm_config_info_t &info)
Get a copy of configuration-dependent information.

## Function Documentation

 static rc_t ss_m::config_info ( sm_config_info_t & info )  [static, inherited]

Get a copy of configuration-dependent information.

Parameters:
 [out] info A pre-allocated structure.
Examples:
create_rec.cpp.

Generated on Mon Jan 2 15:14:02 2012 for Shore Storage Manager by  1.4.7