• DevelopmentEnvSetup

Overview

This document describes the tools you need and the steps you must follow to create a software environment to contribute to the PostBooks and OpenMFG development effort. It assumes that the reader has a software development background, is experienced with downloading software and source code bundles from the Web, and has worked with tools similar to those described below. This document does not describe the only way to do things, just those we have tried with success.

The following tools all have to be present to successfully create a binary version of the PostBooks and OpenMFG applications.

• CVS: One of the source code management tools xTuple uses for version control. Old repositories are currently under CVS control although this might change in the future. New repositories use Subversion.

• Subversion: The other source code management tool xTuple uses for version control.

• Software Development Environment: The particular development tools that xTuple uses or recommends are described below in the sections on particular operating systems. In general, however, the development environment must include a C++ compiler and an application build tool similar to make.

• Qt 4: This is the Graphical User Interface toolkit used to build the PostBooks, OpenMFG, and OpenRPT applications. Qt is available with either a free license for non-commercial development and a commercial license for commercial users.

• To contribute to OpenMFG you must contact Trolltech and get a commercial license for Qt. You should carefully read Trolltech's license before using the Open Source edition for PostBooks development.

• PostgreSQL: PostgreSQL is an open-source database engine at the heart of the PostBooks and OpenMFG applications. Most of the logic of the application is written in PL/pgSQL, the PostgreSQL stored procedure language.

• cURL: cURL is a library and command line file transfer utility that we use because it can retrieve files from the Internet given their URL's.

You will need the following information from xTuple before you begin:

• Version of Qt to get

• Version of PostgreSQL to get

• CVS tag to use when checking out OpenRPT

• Subversion tag to use when checking out postbooks

• Additional information to use when checking out OpenMFG-specific source code.

Setup Steps

Here are the steps you need to follow to create a development environment. Basic goals and platform-independent information are given at the beginning of each step. This is immediately followed by platform-specific information.

Operating System and basic software

Your computer will need an operating system installed and at least a few basic utilities like a web browser. If you are installing an operating system on your hardware, here are a few suggestions for installation options:

• Microsoft Windows: The steps in this document were tested using Windows XP and the Firefox web browser.

• Linux: In addition to the basic workstation packages, install X11 and development tools. The following steps were performed on a computer with the basic Fedora Core 5 installation plus the software development tools selected during the installation.

Basic Development Tools

The GUI client is a large application built in C++. You will need a C++ compiler and a version of the make utility.

Microsoft Windows using MinGW

xTuple recommends using MinGW for developing on Windows although we have also tried Microsoft Visual C++ Express.

1. point your browser to http://sourceforge.net/projects/mingw/

2. click on Download -> SF File Release -> MinGW-version.exe

3. Run the downloaded installer. When it asks which components to install, select at least MinGW base tools, g++ compiler, and MinGW make. Otherwise accept all of the defaults
4. If you want to build PostgreSQL from source, see below.
5. Add the following values to your environment variables.

   PATH
   C:\mingw\bin
   
   INCLUDE
   C:\mingw\include
   
   LIB
   C:\mingw\lib

Microsoft Windows using Visual C++ Express Edition

On Windows xTuple has tried both the Microsoft Visual C++ Express and MinGW development environments. Microsoft Visual C++ Express worked fine, except there were a number of additional steps necessary to distribute binaries to non-build machines and running off of file servers. Also, you have to start with a source distribution of PostgreSQL and build the parts you need. These problems do not seem to occur when using MinGW.

1. point your browser to Microsoft Visual C++ Express web page
2. click on Download Now and follow the instructions
3. accept the defaults (including "Graphical IDE" and excluding
4. both MSDN 2005 Express Edition and SQL Server 2005 Express Edition.
5. Download and install the Microsoft Platform SDK.
6. Add the following values to your environment variables. Be careful, however, to use the short version (8.3 style) of the directory names or you will encounter very strange problems trying to build.

   PATH
   C:\Program Files\Microsoft Visual Studio 8\VC\bin;
   C:\Program Files\Microsoft Visual Studio 8\Common\IDE;
   C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Bin
   
   INCLUDE
   C:\Program Files\Microsoft Visual Studio 8\VC\include;
   C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include
   
   LIB
   C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib

Macintosh OS X

Get and install Xcode:

1. http://developer.apple.com/

2. click Xcode Development Tools -> Tools Downloads -> Xcode version and either sign in if you are an Apple Developer Connection member or sign up if you are not a member yet. This is a huge download (just under 1 Gb), so be prepared to wait for a while and possibly restart the download. You must get Xcode 2.2 or better for Qt versions 4.1 and higher.

3. mount the Xcode disk image

Linux

This step is not necessary if you installed software development tools as part of your Linux operating system installation. If they were not installed at that time, update your installation with packages for C++, build tools, CVS, and other stuff.

Get and install Subversion

You can find binary packages of Subversion for many operating systems at http://subversion.tigris.org/project_packages.html. If you need a graphical user interface environment forSubversion, xTuple suggests usingRapidSVN; several of our developers use it in-house, so we may be able to answer questions about it.

Get and install CVS

CVS is installed with the basic development tools on Macintosh OS X and Linux but you will have to get a version for Windows.

Microsoft Windows

At xTuple we typically use WinCVS as our CVS GUI client although others are available. WinCVS comes bundled with the CVSNT command line tools.

1. Point your web browser to http://www.wincvs.org

2. Click Download -> Latest Recommended Release's Download Installer

3. This takes you to a SourceForge mirror page, where you should select the closest site to your machine.

4. Store the download on your machine.
5. Unzip the file and follow the directions in the Install document. Install both WinCVS and CVSNT, selecting the CVSNT "Typical installation" and defaults for everything else.

Get and install PostgreSQL

Even if you don't run a PostgreSQL database server of your own but instead connect to an existing database server instance, you will need some header files and the libpq library to build PostBooks and OpenMFG. On some platforms you can use binary installations, although xTuple recommends using source installations whenever possible. In any case, start by downloading a distribution:

1. Point your web browser to www.postgresql.org, click on Downloads, then File Browser.

2. If downloading sources, click on the source folder and then click the folder named with the version number you got from xTuple. You need to choose which file format to download based on the compression software you have installed. xTuple recommends downloading the whole distribution (postgresql-version.tar.suffix) as opposed to individual pieces (*base*, *docs*, and *opt*)

See the platform-specific information below if you need to get binary distributions.

PostgreSQL compatibility

Microsoft Windows with MinGW

Install the PostgreSQL binary distribution.

1. Click on binary -> version number from xTuple -> win32 -> postgresql-version-1.zip

2. Extract the contents of the archive to a temporary location, such as your desktop or C:\WINDOWS\Temp\postgres
3. Double-click postgresql-version.msi
4. At minimum you must install the Development packages and the pgcrypto contributed software. You may install more if you like.
5. Now add the necessary include and library directories (using the 8.3 version of the name) to

6. PATH
   C:\Program Files\PostgreSQL\version\bin
   
   INCLUDE
   C:\Program
   Files\PostgreSQL\version\include
   
   LIB
   C:\Program Files\PostgreSQL\version\lib

Microsoft Windows using Visual C++ Express Edition

Use a PostgreSQL source distribution. Microsoft Visual C++ Express is not supported by PostgreSQL and you cannot build the entire database server with it but you can still build the pieces you need.

1. Extract the contents of the archive to C:\postgresql
2. Build libpq:

   cd \postgresql\postgresql-version\src\interfaces\libpq

   • disable the inline keyword by adding the following line at the beginning of ../../backend/mb/wchar.c:

   #define inline

   nmake /f win32.mak

3. Build and install the pgcrypto contributed software for use with credit card processing in the contrib\pgcrypto directory of the distribution.
4. Now add the necessary include and library directories (using the 8.3 version of the name) to

   PATH
   C:\postgresql\postgresql-version\src\interfaces\libpq\Release
   
   INCLUDE
   C:\postgresql\postgresql-version\src\include;
   C:\postgresql\postgresql-version\src\interfaces\libpq
   
   LIB
   C:\postgresql\postgresql-version\src\interfaces\libpq\Release

Macintosh OS X binary installation

We typically recommend a source installation, but it might be possible to use a binary installation of PostgreSQL. Some of our VAR partners report that the Entropy distribution is good, although we have not tried this for a development environment. You can find it here:http://www.entropy.ch/software/macosx/postgresql/.

Macintosh OS X source installation

mkdir /opt/postgresql
cd /opt/postgresql
tar xzvf download-directory/postgresql-version.tar.gz
cd postgresql-version
./configure --prefix=/opt/postgresql/postgresql-version # see table above for other options
make
make check
cd contrib/pgcrypto
make
cd ../..
su
make install
cd contrib/pgcrypto
make install

1. Build and install PostgreSQL by following the directions in the INSTALL file up through and including the gmake install step.
2. Create a directory to hold the PostgreSQL installation.
3. As noted in the INSTALL file, gmake does not exist, so build using make.
4. make check tests the binaries to make sure they work before you install them.
5. Now add the necessary include and library directories to

   PATH
   /opt/postgresql/pg-version/bin
   
   INCLUDE
   /opt/postgresql/pg-version/include
   
   CPATH
   /opt/postgresql/pg-version/lib
   
   LIBRARY_PATH
   /opt/postgresql/pg-version/lib
   
   DYLD_LIBRARY_PATH
   /opt/postgresql/pg-version/li

Modifications for universal binaries on the Macintosh

Building PostgreSQL requires a lot of intervention if you want to create universal binaries:

1. Add the following to the end of the configure line:

   CFLAGS="-arch i386 -arch ppc" LDFLAGS="-arch i386 -arch ppc"

2. Find the Makefiles that combine smaller object files into larger collections:

   grep -rlw LD src

3. In each file found by this command, look for the line that begins SUBSYS.o: and replace the next line, $(LD) $(LDREL) $(LDOUT) SUBSYS.o $(OBJS) with the following:

   $(LD) -arch i386 $(LDREL) $(LDOUT) SUBSYS_i386.o $(OBJS)
   $(LD) -arch ppc $(LDREL) $(LDOUT) SUBSYS_ppc.o $(OBJS)
   lipo -create -arch ppc SUBSYS_ppc.o -arch i386 SUBSYS_i386.o -o SUBSYS.o
   rm SUBSYS_ppc.o SUBSYS_i386.o

4. Replace any other lines that refer to $(LD) with a similar set of changes, but skip the files in the src/makefiles directory and all except the darwin versions of the src/backend/port/*/Makefile files.

5. Edit the src/backend Makefile and change the code that builds postgres to

   $(LD) -arch i386 $(LDREL) $(LDOUT) SUBSYS_i386.o $^
   $(LD) -arch ppc $(LDREL) $(LDOUT) SUBSYS_ppc.o $^
   lipo -create -arch ppc SUBSYS_ppc.o -arch i386 SUBSYS_i386.o -o $@
   rm SUBSYS_ppc.o SUBSYS_i386.o

6. Edit src/Makefiles/Makefile.darwin:

7. define AR = libtool and change AROPT to -o

The attached makeLDuniversal.pl is a PERL script that you can use to edit the Makefiles to do the 4-line LD replacement:

$ perl makeLDuniversal.pl path-to-makefile1 path-to-makefile2 ...

There may still be a problem building universal binaries, so if you get all the way through the build until you see the following:

• make -C src all
  gcc -no-cpp-precomp -arch i386 -arch ppc -Wall -Wmissing-prototypes \
      -Wpointer-arith -Winline -Wdeclaration-after-statement \
      -Wendif-labels -fno-strict-aliasing -bundle pl_gram.o \
      pl_pl_handler.o pl_comp.o pl_exec.o pl_funcs.o \
      -L../../../../src/port \
      -bundle_loader ../../../../src/backend/postgres \
      -o libplpgsql.1.0.so
  /usr/bin/ld: for architecture ppc
  /usr/bin/ld: Undefined symbols:
  _SPI_result
  collect2: ld returned 1 exit status
  /usr/bin/ld: for architecture i386
  /usr/bin/ld: Undefined symbols:
  _SPI_result
  collect2: ld returned 1 exit status

then you can install what you have (not a complete installation but enough to build Qt and run client programs) and continue on to the next step.

Linux

mkdir /opt/postgresql
cd /opt/postgresql
tar xzvf download-directory/postgresql-version.tar.gz
cd postgresql-version
./configure --prefix=/opt --with-openssl
make
make check
su
make install
cd contrib/pgcrypto
make install

1. Build and install PostgreSQL by following the directions in the INSTALL file up through and including the gmake install step.
2. Create a directory to hold the PostgreSQL installation.
3. If gmake does not exist, use make instead.
4. make check tests the binaries to make sure they work before you install them.
5. Now add the necessary include and library directories to

   PATH
   /opt/bin
   
   INCLUDE
   /opt/include
   
   LD_LIBRARY_PATH
   /opt/lib

   While you are at the PostgreSQL web site, you might want to get the pgadmin GUI client as well. After your download of the PostgreSQL source code is complete, back up your web browser two levels and then click on pgadmin3 -> release -> latest version -> os-name -> pgadmin3-version.suffix and install from this bundle.

Get Qt from Trolltech

Get and install Trolltech's Qt. The examples here show the commands for the commercial edition of Qt, but the commands to build and install Qt are the same for the free version.

• If you want to contribute to OpenMFG you must get a commercial license for Qt. This is not necessary if you are contributing to PostBooks.

Windows with MinGW

1. Extract the .zip file to c:\qt
2. In a command window

   cd \qt\qt-win-commercial-src-4.3.2
   configure.exe [ Configuration Parameters from above ] \
            -qt-style-windowsxp -platform win32-g++ \
           -L C:\Progra~1\PostgreSQL\version\lib \
           -I C:\Progra~1\PostgreSQL\version\include
   mingw32-make

3. When Qt has successfully built, add the following values to your environment variables:

   PATH
   c:\qt\qt-win-commercial-src-4.3.2\bin
   
   INCLUDE
   c:\qt\qt-win-commercial-src-4.3.2\include
   
   LIB
   c:\qt\qt-win-commercial-src-4.3.2\lib

   If the Qt build quits without finishing successfully, try adding these environment variables before rebuilding.

   If you use Trolltech's Qt installer to install Qt then you will not have the PostgreSQL drivers available by default. You can however build the drivers after the installation.

   To do this you must have installed PostgreSQL with the development headers and libraries and have the PATH, INCLUDE, and LIBRARY_PATH environment variable setup correctly as described above. Starting a Qt Command Prompt, cd src/plugins/sqldrivers/psql, then make.

Windows with VisualC++ Express Edition

1. Extract the .zip file to

   c:\qt\qt-win-commercial-src-4.3.2 .

2. Start -> Programs -> Microsoft Visual C++ Express Edition -> Visual Studio Tools -> Visual Studio 2005 Command Prompt

3. cd \qt\qt-win-commercial-src-4.3.2
   configure.exe [ Configureation Parameters from above ] -qt-style-windowsxp -platform win32-msvc

4. The configure step will probably fail with a link error in the src\sql subdirectory. If this happens then edit src\sql\Makefile.Release and change the reference from libpq.lib to libpqdll.lib on line ~22, then run nmake from the top level.
5. When Qt has successfully built, add the following values to your environment variables:

   PATH
   c:\qt\qt-win-commercial-src-4.3.2\bin
   
   INCLUDE
   c:\qt\qt-win-commercial-src-4.3.2\include
   
   LIB
   c:\qt\qt-win-commercial-src-4.3.2\lib

   If the Qt build quits without finishing successfully, try adding these environment variables before rebuilding.

Macintosh OS X

On the Macintosh you have a choice of installing a binary or source-code version of Qt. xTuple recommends installing the source-code version. If you are familiar with Xcode and its build framework then you can use the binary distribution of Qt, but xTuple does not support this environment. We have had problems with qmake's handling of nested projects and directory recursion with Xcode and xcodebuild files, which is the build scheme for the Qt binary distributions.

mkdir /opt/qt
cd /opt/qt
tar xzf wherever-the-tarball-is/qt-mac-commercial-src-version.tar.gz
cd qt-mac-commercial-src-version
./configure -prefix-install -prefix /opt/qt/Qt-version [ Configuration Parameters from above ] \
        -I/opt/postgresql/pg-version/include -L/opt/postgresql/pg-version/lib
make
su
make install

1. The -no-framework argument to configure has been selected to reduce the risk of conflict between binary and source installations of Qt. The -I and -L options are not necessary if you installed PostgreSQL in /usr.

• If you want to build universal binaries, then add -universal at the end of the command line. If you do so then you must have built PostgreSQL universal binaries as well. If you want to be able to debug the application all the way down into the Qt libraries then add the --debug-and-release option to the configure command.

Linux

xTuple has not tried building PostBooks and OpenMFG using Qt directly from Linux distribution installations, such as RPMs. If you try doing this then you are on your own.

mkdir /opt/qt
cd /opt/qt
tar xzf whereever-the-tarball-is/qt-x11-commercial-src-version.tar.gz
cd qt-x11-commercial-src-version
./configure -prefix /opt/qt/Qt-version [ Configuration Parameters from above ] -I/opt/include -L/opt/lib -v
make
su
make install

1. The -I and -L options are not necessary if you installed PostgreSQL in /usr.
2. Now add the necessary include and library directories to

   PATH
   /opt/qt/Qt-version/bin
   
   INCLUDE
   /opt/qt/Qt-version/include
   
   LD_LIBRARY_PATH
   /opt/qt/Qt-version/lib

Get and install cURL

Download either the source distribution or the the platform-specific binary distribution of cURL fromhttp://www.haxx.se/curl.

Microsoft Windows with MinGW

1. Download the binary cURL distribution, which consists of the two files curl-version-win32-ssl.zip and libcurl-version-ssl-sspi-sspi.zip and extract the contents of these two .zip files to c:\curl
2. Now set some environment variables:

   INCLUDE
   c:\curl\libcurl-7.15.4\include
   
   LIB
   c:\curl\libcurl-7.15.4\lib
   
   PATH
   c:\curl\curl-7.15.4\bin

Windows with VisualC++ Express Edition

1. Download the source cURL distribution and extract the .zip file contents to c:\curl, then read and follow the directions in docs\INSTALL, in the section named "MSVC from command line":

2. cd c:\curl\curl-version
   vcvars32.bat
   nmake vc

3. Now set some environment variables:

   INCLUDE
   c:\curl\curl-7.15.4\lib
   
   LIB
   c:\curl\curl-7.15.4\lib

Linux

1. Download the source distribution

2. cd /opt/curl
   tar xzvf download-directory/curl-version.tar.gz

3. Build and install cURL with

   cd /opt/curl/curl-version
   ./configure --prefix=/opt
   make
   su
   make install

4. If you used the same --prefix option for configure while building cURL as when building PostgreSQL then you do not have to change any environment variables.

Macintosh

Macintosh XCode comes with cURL pre-installed.

Check out the PostBooks and OpenRPT source code

The example here shows one possible arrangement of source code. There are several that will work. This example uses command line tools, but every reference to svn below can be replaced by commands with RapidSVN.

• mkdir postbooks-checkout-area
  cd postbooks-checkout-area
  svn co https://postbooks.svn.sourceforge.net/svnroot/postbooks postbooks
  cd postbooks/xtuple
  svn co https://openrpt.svn.sourceforge.net/svnroot/openrpt/openrpt/trunk openrpt

Check out the additional OpenMFG source code

If you are working on the OpenMFG application, contact xTuple for information on how to get access to the source code repository.

Build OpenRPT

Next build OpenRPT:

cd OpenRPT-checkout-dir
qmake
make

Mactintosh

Microsoft Windows with MinGW

replace make with mingw32-make

Microsoft Windows with Visual C++ Express Edition

replace make with nmake

Build the main xTuple application

cd postbooks-checkout-dir/xtuple/trunk
qmake
make

Other tools you might need or want

pgadmin

While you are at the PostgreSQL web site, you might want to get the pgadmin GUI client as well. After your download of the PostgreSQL source code is complete, back up your web browser two levels and then click on pgadmin3 -> release -> latest version -> win32 -> pgadmin3-version.zip and install from the .zip file.

ssh

You can get it from http://openssh.org/ for Linux and UNIX variants.

CygWin

If you want to work in a UNIX-like environment you can install the CVS package in CygWin.

• For Windows, install at least a minimal Cygwin configuration and the ssh package from http://www.cygwin.com: From the cygwin home page -> Install or update now! and save setup.exe. Run the setup.exe. You can accept the defaults for most of the steps if you like. If you know the location of any of the download sites on the "Choose A Download Site" page, pick one close to you. Next comes the confusing part, the "Select Packages" page. You can select whatever packages you wish, but for our purposes you specifically need openssh and whatever it depends on. The Cygwin installer setup will help resolve any dependencies if you decide to try skipping anything that it needs. So... scroll down to the Net line and expand the subtree by clicking on the - (-> +) and click on the icon of two arrows making a circle until a check box appears. Make sure there is an X in the openssh checkbox. A few other lines will change at the same time. This is the setup program telling you that these are necessary to make openssh work.

I left everything at the default except for Net, where I set openssh to install. The Cygwin installation process is very robust, so if it stalls at some point and you have to kill it, it will restart essentially where it left off. After Cygwin is installed, make sure your PATH environment variable is set to include the Cygwin bin directory (by default, C:\cygwin\bin).

MSys

1. return to http://www.mingw.org

2. click on Download -> MSYS-version.exe

3. run the msys installer and accept the defaults

4. If you use MinGW and MSYS then you run all of the remaining setup steps in an MSYS window instead of a cmd window. You will also have to use make instead of nmake when you build.

5. To build PostgreSQL, follow the directions in the FAQ_MinGW document in the doc directory.

   cd /c/postgresql/postgresql-version
   ./configure --without-zlib --prefix=/c/postgresql/postgresql-version
   vi src/include/port.h and comment out line 266 (extern def of timezone struct)
   vi src/include/pg_confnig_os.h and comment out lines 151-155 (declaration of struct timezone)
   vi src/port/gettimeofday.c and comment out the implementation of the gettimeofday function
   make
   make check

XSLT Processing

If you want to generate HTML or PDF files from the raw XML documentation files or if you want to integrate the xTuple applications with other systems, you might want to get an XSLT processor. XSLT processors can be used to transform XML files from one format to another, including output as HTML, XML, and plain text.

If you want to integrate the xTuple applications with other systems, you will need an XSLT processor. This will help you transform XML documents produced by other systems, such as Yahoo! stores, into a format which can be directly imported by PostBooks and OpenMFG. Some common XSLT processors include xsltproc, Saxon, and Xalan-C++ and Xalan-J. Saxon and Xalan-J are written in Java and distributed (?) as .jar files. Xalan-C++ is a C++ application and API available from the Apache XML Project. xTuple is considering incorporating Xalan-C++ into its applications to eliminate the need for end-users to download and configure an external XSLT processor.

If this integration occurs, the following should be added to the list of required software:

• xsltproc:

• Saxon:

• Xalan-C++: This is an XSLT processor from the Apache XML Project. It's necessary for processing XML documents for EDI purposes and building documentation from sources.

• Xerces: This is required to build Xalan-C++ and is also available from the Apache XML Project.

Setup Procedure

The following should be added to the setup procedure:

Get and install Xerces

1. Point your web browser to http://www.apache.org/dyn/closer.cgi/xml/xerces-c/

2. Click on source
3. Click on xerces-c-src_2_7_0.tar.gz
4. Extract the sources:

   tar xzf xerces-c-src_2_7_0.tar.gz

5. Follow the build instructions.
   1. Macintosh OS X, refer to:

      xerces-c-src_2_7_0/doc/html/build-other.html#Mac

   2. Make the following changes if you want to build universal binaries:
      1. add the following to the runConfigure command line:

         -z -arch -z ppc -z -arch -z i386

      2. After running runConfigure but before running make, edit Makefile.incl and edit the section for MACOSX (~ line 613). Add -arch ppc -arch i386 at the end of both lines MAKE_SHARED and MAKE_SHARED_C

      3. make install

Get and install Xalan-C++

1. Point your web browser to http://www.apache.org/dyn/closer.cgi/xml/xalan-c

2. Retrieve a source bundle such as Xalan-C_1_10_0-src.tar.gz
3. Extract the sources:

   tar xzf Xalan-C_1_10_0-src.tar.gz

4. Follow the build instructions in xml-xalan/c/README
   1. Macintosh OS X

If you want to build universal binaries, add -arch ppc -arch i386 to the runConfigure command line.

1. make install