<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title> Determining the Scope of the Modifications </title> <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> <link rel="home" href="index.html" title="Porting Berkeley DB" /> <link rel="up" href="newbinary.html" title="Chapter 2. Creating a New Berkeley DB Binary" /> <link rel="previous" href="newbinary.html" title="Chapter 2. Creating a New Berkeley DB Binary" /> <link rel="next" href="buildtarget.html" title=" Building on the Target Platform" /> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center"> Determining the Scope of the Modifications </th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="newbinary.html">Prev</a> </td> <th width="60%" align="center">Chapter 2. Creating a New Berkeley DB Binary</th> <td width="20%" align="right"> <a accesskey="n" href="buildtarget.html">Next</a></td> </tr> </table> <hr /> </div> <div class="sect1" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="modscope"></a> Determining the Scope of the Modifications </h2> </div> </div> <div></div> </div> <p> Once you have a good build of Berkeley DB on a UNIX or UNIX-like system, look over the code to determine what type of code changes you need to make so that you can successfully build Berkeley DB on your target system. This process involves determining: </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> <a href="modscope.html#osfunc"> Do Changes Need to be Made to the Operating System Functionality? </a> </p> </li> <li> <p> <a href="modscope.html#standardfunc">Are Some Standard Functions Missing on the Target Platform?</a> </p> </li> <li> <p> <a href="modscope.html#sharedmem">How Will the Port Handle Shared Memory?</a> </p> </li> <li> <p> <a href="modscope.html#typemutex">What Type of Mutexes Will the Port Use?</a> </p> </li> <li> <p> <a href="modscope.html#otherchanges">Do Any Other Changes Need to be Made?</a> </p> </li> </ul> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="osfunc"></a> Do Changes Need to be Made to the Operating System Functionality? </h3> </div> </div> <div></div> </div> <p> Berkeley DB uses about forty operating system primitives. The Berkeley DB distribution contains files which are wrappers around these operating system primitives that act as an abstraction layer to separate the main Berkeley DB code from operating system and architecture-specific components. You <span class="emphasis"><em>must</em></span> port these files (or versions of these files) whenever you port Berkeley DB to a new platform. </p> <p> Within a Berkeley DB distribution, typically, there is only a single version of these files for all platforms that Berkeley DB supports. Those versions of the files live in the <tt class="literal">os</tt> directory of the distribution and follow the ANSI C and POSIX 1003.1 standards. Within each file, there is usually one, but sometimes several functions (for example, the <tt class="literal">os_alloc.c</tt> file contains the <tt class="literal">malloc</tt>, <tt class="literal">realloc</tt>, <tt class="literal">strdup</tt>, and <tt class="literal">free</tt> functions). The following table describes the files in the os directory of the Berkeley DB distribution. </p> <div class="informaltable"> <table border="1" width="80%"> <colgroup> <col /> <col /> </colgroup> <thead> <tr> <th> <p> Source file </p> </th> <th> <p> Description </p> </th> </tr> </thead> <tbody> <tr> <td> <p> os_abort.c </p> </td> <td> <p> abort() </p> </td> </tr> <tr> <td> <p> os_abs.c </p> </td> <td> <p> Return if a filename is an absolute path name </p> </td> </tr> <tr> <td> <p> os_addrinfo.c </p> </td> <td> <p> getaddrinfo(), freeaddrinfo() </p> </td> </tr> <tr> <td> <p> os_alloc.c </p> </td> <td> <p> malloc(), realloc(), strdup(), free() </p> </td> </tr> <tr> <td> <p> os_clock.c </p> </td> <td> <p> clock_gettime() </p> </td> </tr> <tr> <td> <p> os_config.c </p> </td> <td> <p> Minor run-time configuration information </p> </td> </tr> <tr> <td> <p> os_ctime.c </p> </td> <td> <p> ctime() </p> </td> </tr> <tr> <td> <p> os_dir.c </p> </td> <td> <p> Return a list of files for a directory </p> </td> </tr> <tr> <td> <p> os_errno.c </p> </td> <td> <p> Library and system error translation </p> </td> </tr> <tr> <td> <p> os_fid.c </p> </td> <td> <p> Return a unique identifier for a file </p> </td> </tr> <tr> <td> <p> os_fsync.c </p> </td> <td> <p> fsync() </p> </td> </tr> <tr> <td> <p> os_handle.c </p> </td> <td> <p> Return a file handle </p> </td> </tr> <tr> <td> <p> os_pid.c </p> </td> <td> <p> Return a unique identifier for a threa </p> </td> </tr> <tr> <td> <p> os_map.c </p> </td> <td> <p> Shared memory mapping </p> </td> </tr> <tr> <td> <p> os_mkdir.c </p> </td> <td> <p> mkdir() </p> </td> </tr> <tr> <td> <p> os_oflags.c </p> </td> <td> <p> open() Used to convert open flags to Berkeley DB flags </p> </td> </tr> <tr> <td> <p> os_open.c </p> </td> <td> <p> Return a file handle </p> </td> </tr> <tr> <td> <p> os_rename.c </p> </td> <td> <p> rename() </p> </td> </tr> <tr> <td> <p> os_root.c </p> </td> <td> <p> Return if application has special permissions </p> </td> </tr> <tr> <td> <p> os_rpath.c </p> </td> <td> <p> Return last separator in a path </p> </td> </tr> <tr> <td> <p> os_rw.c </p> </td> <td> <p> read(), write() </p> </td> </tr> <tr> <td> <p> os_seek.c </p> </td> <td> <p> lseek() </p> </td> </tr> <tr> <td> <p> os_sleep.c </p> </td> <td> <p> sleep() </p> </td> </tr> <tr> <td> <p> os_spin.c </p> </td> <td> <p> Return the number of test-and-set mutex spins before blocking </p> </td> </tr> <tr> <td> <p> os_stat.c </p> </td> <td> <p> stat() </p> </td> </tr> <tr> <td> <p> os_tmpdir.c </p> </td> <td> <p> Return the directory name used by the system for temporary files </p> </td> </tr> <tr> <td> <p> os_truncate.c </p> </td> <td> <p> ftruncate() </p> </td> </tr> <tr> <td> <p> os_uid.c </p> </td> <td> <p> Return unique 32-bit id </p> </td> </tr> <tr> <td> <p> os_unlink.c </p> </td> <td> <p> unlink() </p> </td> </tr> <tr> <td> <p> os.yield.c </p> </td> <td> <p> yield() </p> </td> </tr> </tbody> </table> </div> <p> When the operating system primitives on the target platform are identical or close to the POSIX semantics that Berkeley DB requiress, then no code changes or minimal code changes to the files in the <tt class="literal">os</tt> directory are required. If the operating system primitives are quite different, then some code changes may be required to bridge the gap between the requirements of Berkeley DB and what the operating system provides. </p> <p> Where different code is required, you write an entirely different version of the file and place it in an <tt class="literal">os</tt>_<span class="emphasis"><em>xxx</em></span> directory where <span class="emphasis"><em>xxx</em></span> represents a platform name. There are <tt class="literal">os</tt>_<span class="emphasis"><em>xxx</em></span> subdirectories in the Berkeley DB distribution for several established non-POSIX platforms. For example, there is a he <tt class="literal">os_vxworks</tt> directory that contains VxWorks versions of some of the files in the os directory, and Windows versions of some files are in the <tt class="literal">os_windows</tt> directory. If your target platform needs a different version of a file, you will need to write that file and place it in a new <tt class="literal">os</tt>_<span class="emphasis"><em>xxx</em></span> directory that you create for your target platform. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="standardfunc"></a>Are Some Standard Functions Missing on the Target Platform?</h3> </div> </div> <div></div> </div> <p> In some cases, the target platform may not provide the few POSIX functions required by Berkeley DB or the functions provided by the target platform may not operate in a standard compliant way. Berkeley DB provides replacement functionsin the <tt class="literal">clib</tt> directory of the Berkeley DB distribution. </p> <p> You need to determine how your target platfrom handles these functions: </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> When the target platform does <span class="emphasis"><em>not</em></span> have a POSIX function required by Berkeley DB, no action is required on your part. When Berekely DB cannot find one of these functions on the target platform, it automatically uses the replacement functions supplied in the <tt class="literal">clib</tt> directory of the Berkeley DB distribution. For example, if the target platform does not have the <tt class="literal">atoi</tt> or <tt class="literal">strtol</tt> functions, Berkeley DB uses <tt class="literal">clib/atoi.c</tt> and <tt class="literal">clib/strtol.c</tt>. </p> </li> <li> <p> When the target platform has a function required by Berekely DB, but that function operates in a non-standard compliant way, you can code to the replacement functions supplied in the <tt class="literal">clib</tt> directory. </p> </li> </ul> </div> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="sharedmem"></a>How Will the Port Handle Shared Memory?</h3> </div> </div> <div></div> </div> <p> In order to write multiprocess database applications (not multithreaded, but threads of control running in different address spaces), Berkeley DB must be able to name pieces of shared memory and access them from multiple processes. </p> <p> On UNIX/POSIX systems, Berkeley DB uses <tt class="literal">mmap</tt> and <tt class="literal">shmget</tt> for that purpose, but any interface that provides access to named shared memory is sufficient. If you have a simple, flat address space, you should be able to use the code in <tt class="literal">os_vxworks/os_map.c</tt> as a starting point for the port. </p> <p> If you are not intending to write multiprocess database applications, then this won't be necessary, as Berkeley DB can simply allocate memory from the heap if all threads of control will live in a single address space. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="typemutex"></a>What Type of Mutexes Will the Port Use?</h3> </div> </div> <div></div> </div> <p> Berkeley DB requires some form of self-blocking mutual exclusion mutex. Blocking mutexes are preferred as they tend to be less CPU-expensive and less likely to cause thrashing. If blocking mutexes are not available, however, test-and-set will work as well. The code for mutexes is in two places in the system: the include file <tt class="literal">dbinc/mutex_int.h</tt>, and the distribution directory <tt class="literal">mutex</tt>. </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="otherchanges"></a>Do Any Other Changes Need to be Made?</h3> </div> </div> <div></div> </div> <p> In most cases, you do not need to make any changes to the Berkeley DB source code that is not in the abstraction layer (that is, that is in the <tt class="literal">os</tt> directory) as that code is designed to be platform-independent code. However, in some situations, the compiler for the target platform is non-standard and may raise errors when compiling some aspects of the Berkeley DB code (for example, additional casting may be required, or a certain type may cause a problem). In these cases, you will need to modify the generic Berkeley DB code in order to have error-free compilation. </p> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="newbinary.html">Prev</a> </td> <td width="20%" align="center"> <a accesskey="u" href="newbinary.html">Up</a> </td> <td width="40%" align="right"> <a accesskey="n" href="buildtarget.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">Chapter 2. Creating a New Berkeley DB Binary </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Building on the Target Platform</td> </tr> </table> </div> </body> </html>