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:
  --enable-pthread-mutex default:yes    Compile to use pthreads for mutexes for
                                        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.

• HUGETLBFS_PATH See --with-hugetlbfs in Configuration Options; see also Huge Pages for use of hugetlbfs with Linux.

• 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

• ActiveState (http://www.activestate.com/activetcl/), or
• SourceForge (http://sourceforge.net/projects/tcl/files/).

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:

• the header files in
  • <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.

---