Feature Data Objects (FDO) OpenSource README
============================================
This ReadMe contains important information required to build FDO open source.
Ensure you read through this document before building.
Contents:
Windows Instructions
- Build Instructions
- Build Notes
- Running the FDO Unit Tests
Linux Instructions
- Build Instructions
- Build Notes
- Running the FDO Unit Tests
-----------------------------
Windows Instructions
-----------------------------
I. Build Instructions
1. cd [FDO OpenSource]
2. Open and modify setenvironment.bat to specify the locations of the Thirdparty SDK
components and build tools. (Refer to Build notes below)
3. call setenvironment.bat
4. call build_thirdparty.bat
5. call build.bat
II. Build Notes
In preparation for building the Windows Open Source FDO Binaries:
1. The FDO open source build process supports the usage of either the Visual
Studio Express, Standard or Professional editions.
The Visual Studio Express software can be download and installed for
free from the following sites.
Visual Studio C# Express Edition:
http://msdn.microsoft.com/vstudio/express/visualcsharp/download/
Visual Studio C++ Express Edition:
http://msdn.microsoft.com/vstudio/express/visualc/download/
In order to build the FDO Components using Visual Studio Express, you are also
required to download and install the Windows® Server 2003 R2 Platform SDK.
Download the Windows® Server 2003 R2 Platform SDK from:
http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en
NOTE: The Windows® Server 2003 R2 Platform SDK is composed of many components.
The only components required for building FDO are:
- Microsoft Windows Core SDK
- Microsoft Data Access Services (MDAC) SDK
- Microsoft Web Workshop (IE) SDK
You can limit you installation to these components only.
The easiest procedure to use the PSDK with VC2005 Express is:
a) Create a directory "PlatformSDK" under "%ProgramFiles%\Microsoft Visual Studio 8\VC"
b) Copy the "bin", "include" and "lib" directory from the PSDK-installation into this directory.
2. Install ActiveState Perl, available from:
http://www.activestate.com/ActivePerl
3. Ensure that the Windows Environment Variables are set as follows:
SET FDO=[FDO OpenSource]\Fdo
SET FDOUTILITIES=[FDO OpenSource]\Utilities
SET FDOTHIRDPARTY=[FDO OpenSource]\ThirdParty
SET XALANROOT=%FDOTHIRDPARTY%\apache\xml-xalan\c
SET XERCESCROOT=%FDOTHIRDPARTY%\apache\xml-xerces\c
SET NLSDIR=%XALANROOT%\Src\xalanc\NLS
4. In order to build all FDO Windows components, ensure that the Microsoft
MsBuild tool that is used by the the FDO build process is included in
the Windows system PATH.
set PATH=%PATH%;C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
5. In order to build the ArcSDE Provider, you will need to have the
ArcSDE 9.1 Client SDK installed and the following environment variable
set that points to the installation location:
set SDEHOME=[ArcSDE developer components path]
Note that ArcSDE is licensed software and must be obtained from an ESRI vendor.
6. In order to build the MySQL Provider, you will need to download
and install the MySQL 5.0 Windows client and developer components from:
http://dev.mysql.com/downloads/mysql/5.0.html
Following the installation, set the following FDO Windows environment variable:
set FDOMYSQL=[MySQL developer components path]
e.g. set FDOMYSQL=c:\Program Files\MySQL\MySQL Server 5.0
7. OPTIONAL: The FDO build includes several generated .cpp files that were
generated from source .y files by the Bision and Sed utilities. These
files are fairly static therefore they are not automatically regenerated
as a part of the standard FDO build process. If changes are made
to the .y files they will need to be recompiled into their respective
.cpp and .h files.
In order to rebuild these files download and install the GNU
Win32 Bison (version 1.875) and Sed (version 4.1.4) self-extracting utilities.
"Bison"
Bison is a general-purpose parser generator that converts a grammar
description for an LALR context-free grammar into a C program to parse
that grammar.
Home Page:
http://gnuwin32.sourceforge.net/packages/bison.htm
Download Location:
http://prdownloads.sourceforge.net/gnuwin32/bison-1.875-1.exe?download
"Sed"
Sed (streams editor) isn't really a true text editor or text processor.
Instead, it is used to filter text, i.e., it takes text input and performs
some operation (or set of operations) on it and outputs the modified text.
Sed is typically used for extracting part of a file using pattern matching
or substituting multiple occurrences of a string within a file.
Home Page:
http://gnuwin32.sourceforge.net/packages/sed.htm
Download Location:
http://prdownloads.sourceforge.net/gnuwin32/sed-4.1.4.exe?download
FDO has been tested using Bison 1.875 and Sed 4.1.4 and will not work with
other versions of these binaries. The Bison and Sed executable files MUST be
included in the Windows PATH in order to be used by the FDO build process.
e.g. set PATH=%PATH%;C:\Program Files\GnuWin32\bin
The optional FDO build script that will need to be executed to rebuild the
generated cpp source files is:
build_parse.bat
8. OPTIONAL: The FDO build process allows it's documentation to be regenerated.
If this is required, install the OpenSource Doxygen documentation generation
software. Doxygen is a documentation system for C++, C, Java, Objective-C,
Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.
To install Doxygen, refer to: http://www.stack.nl/~dimitri/doxygen/
The FDO Doxygen documentation generation process will also use the "dot" tool
from graphviz 1.5 to generate more advanced diagrams and graphs. Graphviz is an
"open-sourced", cross-platform graph drawing toolkit from AT&T and Lucent
Bell Labs.
To install graphviz, refer to: http://www.graphviz.org/
The FDO Doxygen documentation generation process also uses the Microsoft
HTML Help Workshop. Microsoft HTML Help is the standard help system for the
Windows platform. Authors can use HTML Help to create online help for a
software application or to create content for a multimedia title or Web site.
To install the Microsoft HTML Help Workshop, refer to:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
Ensure that the tools are in the build environment's PATH.
Doxygen -- e.g. C:\Program Files\doxygen\bin
Dot -- e.g. C:\Program Files\ATT\Graphviz\bin
e.g.
set PATH=%PATH%;C:\Program Files\doxygen\bin
set PATH=%PATH%;C:\Program Files\ATT\Graphviz\bin
9. Use the [FDO OpenSource]\setenvironment.bat script to assist in setting and
maintaing the correct environment settings for the FDO build process.
This script can be modifed and used to set the correct environment variables
and PATH settings.
10. The build_thirdparty.bat file is ude to build the FDO Thirdparty binaries. The following
is a general guideline on how to use the build_thirdparty.bat build script.
**************************************************************************
build_thirdparty.bat [-h]
[-o=OutFolder]
[-c=BuildType]
[-a=Action]
[-w=WithModule]
Help: -h[elp]
OutFolder: -o[utpath]=destination folder for binaries
BuildType: -c[onfig]=release(default), debug
Action: -a[ction]=build(default), buildinstall, install, clean
WithModule: -w[ith]=all(default), fdo, providers, sdf, wfs, wms
**************************************************************************
e.g.
**** Display help for build.bat
build_thirdparty -h
**** Build all Thirdparty components
build_thirdparty
**** Build all Thirdparty components and install output files to C:\Fdo
build_thirdparty -a=buildinstall -o=C:\Fdo
**** Build Thirdparty components required to build the FDO API libraries
build_thirdparty -w=fdo
**** Build Thirdparty components for all FDO Providers
build_thirdparty -w=providers
**** Build Thirdparty components for for the SDF Provider
build_thirdparty -w=sdf
**** Build Thirdparty components for for the WMS and WFS Providers
build_thirdparty -w=wms -w=wfs
11. The build.bat file is used to build the FDO binaries. The following
is a general guideline on how to use the build.bat build script.
**************************************************************************
build.bat [-h]
[-o=OutFolder]
[-c=BuildType]
[-a=Action]
[-w=WithModule]
[-d=BuildDocs]
Help: -h[elp]
OutFolder: -o[utpath]=destination folder for binaries
BuildType: -c[onfig]=release(default), debug
Action: -a[ction]=build(default),
buildinstall,
install,
clean
WithModule: -w[ith]=all(default),
fdo,
providers,
shp,
sdf,
wfs,
wms,
arcsde,
odbc,
mysql,
gdal
BuildDocs: -d[ocs]=skip(default), build
**************************************************************************
e.g.
**** Display help for build.bat
build -h
**** Build all components excluding documentation
build
**** Build all components and install output files to C:\Fdo
build -a=buildinstall -o=C:\Fdo
**** Build all components and documentation and install files to C:\Fdo
build -a=buildinstall -o=C:\Fdo -d=build
**** Build only FDO libraries
build -w=fdo
**** Build all FDO Providers
build -w=providers
**** Build the FDO Shape Provider
build -w=shp
**** Build the FDO SDF Provider
build -w=sdf
**** Build the FDO WMS and WFS Providers
build -w=wms -w=wfs
**** Build documentation and install all files to C:\Fdo
build -a=install -o=C:\Fdo -d=build
III. Running the FDO Unit Tests
The FDO API and the FDO providers come with unit tests that will allow the various
products to be tested once the build is complete. In order to run the FDO API,
WMS, SHP, SDF, ArcSDE, GDAL, MySql and Odbc Provider Unit Tests, follow the following
instructions once the build has completed
FDO:
cd [FDO OpenSource]\Fdo\Unmanaged\bin\win32\Debug
Run UnitTest.exe
WMS:
cd [FDO OpenSource]\Providers\WMS\bin\win32\debug
Run UnitTest.exe
SDF:
cd [FDO OpenSource]\Providers\SDF\Src\UnitTest
Run ..\..\bin\win32\Debug\UnitTest.exe
SHP:
cd [FDO OpenSource]\Providers\SHP\Src\UnitTest
Run ..\..\bin\win32\Debug\UnitTest.exe
ArcSDE:
NOTE: Please refer to [FDO OpenSource]\Providers\ArcSDE\UnitTest_README.txt
for details on how to create test users and test data, and which command-line arguments
to pass to the ArcSDE Provider UnitTest executable in order to point to your
test server and data.
cd [FDO OpenSource]\Providers\ArcSDE\Src\UnitTest
Run ..\..\bin\win32\Debug\UnitTest.exe [mandatory command-line arguments]
GDAL:
cd [FDO OpenSource]\Providers\GDAL\Src\UnitTest
Run ..\..\Bin\Win32\Debug\UnitTest.exe
MySql:
cd [FDO OpenSource]\Providers\GenericRdbms\Src\UnitTest
If you wish to run the MySql unit tests without specifying
an initialization file, update the default initialization file
"MySqlInit.txt" file with valid values for username, password and service
for the service against which the unit tests should be executed and
run "Dbg\UnitTestMySql.exe" with no additional parameters.
NOTE: Do not drop MySqlInit.txt in subversion if you choose to modify it
If you wish to run the unit test and specify your own
initialization file, create your the file with valid values for username,
password and service and run the unit test by specifying the initialization file
on the command line when executing the unit tests.
e.g. Dbg\UnitTestMySql.exe initfiletest=MySqlInitEx.txt
NOTE: The initialization file must contain values for service, username and password.
e.g.: service=mysqlserver;username=root;password=xxxx;
Odbc:
cd [FDO OpenSource]\Providers\GenericRdbms\Src\UnitTest
If you wish to run the ODBC unit tests without specifying
an initialization file, update the default initialization file
"OdbcInit.txt" file with valid values for username, password and service
for the services against which the unit tests should be executed and
run "Dbg\UnitTestOdbc.exe" with no additional parameters.
NOTE: Do not drop OdbcInit.txt in subversion if you choose to modify it
If you wish to run the unit test and specify your own
initialization file, create your the file with valid values for username,
password and the service names. Run the unit test by specifying the
initialization file on the command line when executing the unit tests.
e.g. Dbg\UnitTestOdbc.exe initfiletest=OdbcInitEx.txt
NOTE: The initialization file must contain values for service, username and password.
The initialization file must contain service, username and password for each server type
DSN name can be specified using DSNOracle, DSNMySql, DSNSqlServer
e.g.:
serviceOracle=oraserver;usernameOracle=xxxx;passwordOracle=xxxx;DSNOracle=ORACLExxx;
serviceMySql=mysqlserver;usernameMySql=root;passwordMySql=xxxx;DSNMySql=MySQLxxx;
serviceSqlServer=sqlserver;usernameSqlServer=xxxx;passwordSqlServer=xxxx;DSNSqlServer=SqlServerxxx;
NOTE: You can also run the unit tests separately for each ODBC subtype:
MySql: Dbg\UnitTestOdbc.exe OdbcMySqlTests
Oracle: Dbg\UnitTestOdbc.exe OdbcOracleTests
SqlServer: Dbg\UnitTestOdbc.exe OdbcSqlServerTests
Access: Dbg\UnitTestOdbc.exe OdbcAccessTests
Excel: Dbg\UnitTestOdbc.exe OdbcExcelTests
Text: Dbg\UnitTestOdbc.exe OdbcTextTests
-----------------------------
Linux Instructions
-----------------------------
I. Build Instructions
1. cd [FDO OpenSource]
2. Open and modify setenvironment.sh to specify the locations of the Thirdparty SDK
components and build tools. (Refer to Build notes below)
3. source ./setenvironment.sh
4. ./build_thirdparty.sh
5. ./build_linux.sh
NOTE: build_linux.sh is a simple helper script that assists developers to build the FDO
components. These scripts supplement standard support of configure and make.
The implementation of the above build_linux.sh script in essence calls ...
aclocal
libtoolize --force
automake --add-missing --copy
autoconf
./configure
make
make install
for the fdo core API components as well as the set of FDO providers that are
currently supported in the automated build process. Users are free to call configure
and make without using the build_linux.sh helper script.
II. Build Notes
In preparation for building the Linux Open Source FDO Binaries
1. Before building FDO and thirdparty libraries, the /usr/local
directory must be set as writeable by the user, otherwise the user
will have to log in and build FDO as the ROOT user. This requirement
is due to the fact that the FDO Libraries will be built and installed
in /usr/local/fdo-3.2.0/lib
2. Ensure that the following FDO Environment Variables are set as follows:
FDO = [FDO OpenSource]/Fdo
FDOUTILITIES = [FDO OpenSource]/Providers/Utilities
FDOTHIRDPARTY = [FDO OpenSource]/ThirdParty
3. In order to build the ArcSDE Provider, you will need to have the
ArcSDE 9.1 Client SDK installed and the following environment variable set that
points to the installation location:
SDEHOME=[ArcSDE developer components path]
Note that ArcSDE is licensed software and must be obtained from an ESRI vendor.
4. In order to build the MySQL Provider, you will need to download and extract
the MySQL client and MySQL 5.0 devloper components from MySQL. These
components are located at:
http://dev.mysql.com/downloads/mysql/5.0.html
For example, for Red Hat Enterprise Linux 3 RPM (x86)
Client: MySQL-client-standard-5.0.22-0.rhel3.i386.rpm
Headers and Libraries: MySQL-devel-standard-5.0.22-0.rhel3.i386.rpm
NOTE: Choosing the RPM install of the MySQL components is *strongly*
recommended. However, if a non-RPM installation of MySQL is chosen,
following the installation, set the following FDO environment variable:
FDOMYSQL=[MySQL developer components path]
5. In order to build the ODBC Provider, you will need to either
a) download and install the Linux ODBC driver Manager, specifically
the unixODBC-CORE and unixODBC-devel packages relased by www.unixodbc.org
Home Page:
http://www.unixodbc.org/
Download Location:
http://sourceforge.net/project/showfiles.php?group_id=1544
Download Files:
unixODBC-CORE - unixODBC-2.2.11-1.i386.rpm
unixODBC-devel - unixODBC-devel-2.2.11-1.i386.rpm
Such an installation will install the unixODBC driver manager libraries
and header files in
usr/lib and usr/include
The FDO ODBC provider build will automatically locate thee files in this liocation.
b) install an unixODBC driver such as the EasySofy Oracle ODBC driver. This installation
will include the driver libraries as well as the unixODBC manager libraries.
If such an installation occurs the manager libraries and headers will not be
installed under /usr/lib or usr/include but will be installed in a custom location
as specified by the driver RPM package. If this is the case, you will need to set
the following FDO environment variable to point to the location of the unixODBC
components:
FDOODBC=[unixODBC developer components path]
6. OPTIONAL: The FDO build process allows it's documentation to be regenerated.
If this is required, install the OpenSource Doxygen documentation generation
software. Doxygen is a documentation system for C++, C, Java, Objective-C,
Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D.
Doxygen is often automataically installed on Fedora Core and RedHat systems.
To install Doxygen, refer to: http://www.stack.nl/~dimitri/doxygen/
The FDO Doxygen documentation generation process will also use the "dot" tool
from graphviz 1.5 to generate more advanced diagrams and graphs. Graphviz is an
"open-sourced", cross-platform graph drawing toolkit from AT&T and Lucent
Bell Labs.
To install graphviz, refer to: http://www.graphviz.org/
7. NOTE: To run the unit test, you must set LD_LIBRARY_PATH as follows:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/fdo-3.2.0/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SDEHOME/lib:$FDOTHIRDPARTY/ESRI/ArcSDEClient91/Linux/lib
8. NOTE: Several known problems exist if auto-mounted drives are used as locations
for the FDO Linux builds. It is recommended that users not use auto-mounted drives
when building FDO.
9. NOTE: The FDO expression scripts (.y) are not automatially recompiled as a part of the
FDO build process. In order to recompile the .y files into their .cpp and .h
counterparts, execute the build_parse.sh script.
10. NOTE: Use the [FDO OpenSource]\setenvironment.sh script to assist in setting and
maintaing the correct environment settings for the FDO build process.
This script can be modifed and used to set the correct environment variables
and PATH settings.
11. The build_thirdparty.sh script is used to build the FDO Thirdparty binaries.
The following is a general guideline on how to use the build_thirdparty.bat build script.
**************************************************************
build_thirdparty.sh [--h] [--a Action] [--m ConfigMakefiles]
Help: --h[elp]
Action: --a[ction] buildinstall(default),
build,
install,
uninstall,
clean
ConfigMakefiles: --m[akefile] configure(default), noconfigure
**************************************************************
e.g.
**** Display help for build_thirdparty.sh
build_thirdparty --h
**** Configure, Build and Install all Thirdparty components
build_thirdparty
**** Uninstall all Thirdparty components
build_thirdparty --a uninstall
**** Clean up all Thirdparty components
build_thirdparty --a clean
12. The build_linux.sh script is used to build and install the FDO OpenSource
libraries. The following is a general guideline on how to use build_linux.sh
**************************************************************
build_linux.sh [--h]
[--c BuildType]
[--a Action]
[--w WithModule]
[--d BuildDocs]
[--m ConfigMakefiles]
Help: --h[elp]
BuildType: --c[onfig] release(default), debug
Action: --a[ction] buildinstall(default),
build,
install,
uninstall,
clean
BuildDocs: --d[ocs] skip(default), build
ConfigMakefiles: --m[akefile] configure(default), noconfigure
WithModule: --w[ith] fdocore(default),
fdo,
thirdparty,
providers,
shp,
sdf,
wfs,
wms,
arcsde,
rdbms,
gdal
**************************************************************
e.g.
**** Display help for build.bat
build_linux.sh --h
**** Configure, Build and Install all components
build_linux.sh
**** Configure and Build all components
build_linux.sh --a build
**** Build all components without running configure
build_linux.sh --a build --m noconfigure
**** Configure and Install all components
build_linux.sh --a install
**** Configure and Build only the FDO library
build_linux.sh --a build -w fdo
**** Configure and Build all FDO Providers
build_linux.sh --a build --w providers
**** Configure and Build only the SHP Provider
build_linux.sh --a build --w shp
**** Configure and Build only the SDF Provider
build_linux.sh --a build --w sdf
**** Configure and Build both the WMS and WFS Providers
build_linux.sh --a build --w wms --w wfs
III. Running the FDO Unit Tests
The FDO API and the FDO providers come with unit tests that will allow the various
products to be tested once the build is complete. In order to run the FDO API,
WMS, SHP, SDF, ArcSDE, GDAL, MySql and Odbc Provider Unit Tests, follow the following
instructions once the build has completed
FDO:
cd [FDO OpenSource]/Fdo/UnitTest
./UnitTest
WMS:
cd [FDO OpenSource]/Providers/WMS/Src/UnitTest
./UnitTest
SDF:
cd [FDO OpenSource]/Providers/SDF/Src/UnitTest
./UnitTest
SHP:
cd [FDO OpenSource]/Providers/SHP/Src/UnitTest
./UnitTest
ArcSDE:
Please refer to [FDO OpenSource]/Providers/ArcSDE/UnitTest_README.txt
for details on how to create test users and test data, and which
command-line arguments to pass to the ArcSDE Provider UnitTest
executable in order to point to your test server and data.
cd [FDO OpenSource]/Providers/ArcSDE/Src/UnitTest
./UnitTest [mandatory command-line arguments]
e.g.
./UnitTest server=somesite.com port_multi=5151/tcp port_single=5151/tcp sdepwd=test dataset=FC4 rdbms=ORACLE
GDAL:
cd [FDO OpenSource]/Providers/GDAL/Src/UnitTest
./UnitTest
MySql:
cd [FDO OpenSource]/Providers/GenericRdbms/Src/UnitTest
If you wish to run the MySql unit tests without specifying
an initialization file, update the default initialization file
"MySqlInit.txt" file with valid values for username, password and service
for the service against which the unit tests should be executed and
run ./UnitTestMySql with no additional parameters.
NOTE: Do not drop MySqlInit.txt in subversion if you choose to modify it
If you wish to run the unit test and specify your own
initialization file, create your the file with valid values for username,
password and service and run the unit test by specifying the initialization file
on the command line when executing the unit tests.
e.g. ./UnitTestMySql initfiletest=MySqlInitEx.txt
NOTE: The initialization file must contain values for service, username and password.
e.g.: service=mysqlserver;username=root;password=xxxx;
Odbc:
cd [FDO OpenSource]/Providers/GenericRdbms/Src/UnitTest
you must have the DSN created before you will run the unit tests.
DSN name can be specified using DSNOracle, DSNMySql, DSNSqlServer
If you wish to run the ODBC unit tests without specifying
an initialization file, update the default initialization file
"OdbcInit.txt" file with valid values for username, password and service
for the services against which the unit tests should be executed and
run ./UnitTestOdbc with no additional parameters.
NOTE: Do not drop OdbcInit.txt in subversion if you choose to modify it
If you wish to run the unit test and specify your own
initialization file, create your the file with valid values for username,
password and the service names. Run the unit test by specifying the
initialization file on the command line when executing the unit tests.
e.g. ./UnitTestOdbc initfiletest=OdbcInitEx.txt
NOTE: The initialization file must contain values for service, username and password.
The initialization file must contain service, username and password for each server type
e.g.:
serviceOracle=oraserver;usernameOracle=xxxx;passwordOracle=xxxx;DSNOracle=ORACLE;
serviceMySql=mysqlserver;usernameMySql=root;passwordMySql=xxxx;DSNMySql=MySQL;
NOTE: You can also run the unit tests separately for each ODBC subtype:
MySql: ./UnitTestOdbc OdbcMySqlTests
Oracle: ./UnitTestOdbc OdbcOracleTests
[end]