\division{Building and Testing the OS Project}\label{section:build}


Once the OS source code is obtained, the OS libraries, {\tt OSSolverService}\index{OSSolverService@{\tt OSSolverService}} 
executable, and test examples can be built.
We describe how to do this on Unix/Linux\index{Unix} systems (see Section~\ref{section:unixbuilds})
and on Windows\index{Microsoft Windows} (see Section~\ref{section:windowsinstall}).

\subdivision{Building the OS Project on Unix/Linux Systems}\label{section:unixbuilds}

In order to build the OS project on Unix/Linux systems do the following.

\vskip 8pt

\begin{enumerate}[{\bf Step 1:}]
\item{} Connect to the OS distribution root directory ({\tt COIN-OS} in Figure~\ref{figure:osprojectrootdir}).

\vskip 8pt



\item{} \label{itemize:unixbuilds} Run the configure script that will generate the makefiles.
If you are running on a machine with a Fortran\index{Fortran} 95 compiler present (e.g., {\tt gfortran}), and you have
previously downloaded the third-party software packages {\tt BLAS}\index{Third-party software!Blas} 
and {\tt Mumps}\index{Third-party software!Mumps}
(see Section~\ref{section:ipopt}), run the command

\begin{verbatim}
./configure
\end{verbatim}
\index{configure}

\noindent otherwise use

\begin{verbatim}
./configure  COIN_SKIP_PROJECTS="Ipopt Bonmin"
\end{verbatim}
\index{COIN_SKIP_PROJECTS@{\tt COIN\_SKIP\_PROJECTS}}
as COIN-OR's {\tt Ipopt}\index{COIN-OR projects!Ipopt@{\tt Ipopt}} and
{\tt Bonmin}\index{COIN-OR projects!Bonmin@{\tt Bonmin}}
projects currently use Fortran to compile some of its dependent libraries.

\vskip 8pt
\noindent {\bf Notes:}

\begin{itemize}
\item If {\tt gfortran} is not present and you  wish to build the nonlinear solver {\tt Ipopt} see the instructions 
in Section~\ref{section:ipopt}.

\item When using {\tt configure} you may wish to use the {\tt -C} option. This
instructs {\tt configure} to use a cache file, {\tt config.cache}\index{configure!cache file}, to speed up configuration
by remembering and reusing the results of tests already performed.

\item For more information and options on the {\tt ./configure} script see

\noindent{\footnotesize {\tt\UrlCoinConfig}.}

\item You  cannot apply  {\tt COIN\_SKIP\_PROJECTS}\index{COIN_SKIP_PROJECTS@{\tt COIN\_SKIP\_PROJECTS}} to 
{\tt Cbc}\index{COIN-OR projects!Cbc@{\tt Cbc}}, 
{\tt Clp}\index{COIN-OR projects!Clp@{\tt Clp}}, 
{\tt Cgl}\index{COIN-OR projects!Cgl@{\tt Cgl}}, 
{\tt CoinUtils}\index{COIN-OR projects!CoinUtils@{\tt CoinUtils}}, 
%{\tt CppAD}\index{COIN-OR projects!CppAD@{\tt CppAD}}, 
or {\tt Osi}\index{COIN-OR projects, {\tt Osi}}.
These projects must be present.
\end{itemize}



\item{}  Run the make files.

\index{make@{\tt make}}
\begin{verbatim}
make
\end{verbatim}

\item{} Run the {\tt unitTest}\index{unitTest@{\tt unitTest}}.

\index{make test@{\tt make test}}
\begin{verbatim}
make test
\end{verbatim}

\ifknitro
Depending upon which third-party software you have installed, the result of running the {\tt unitTest} should look
something like (we have included the third-party solvers LINDO\index{LINDO} and Knitro\index{Knitro} in the test 
results below; they are not part of the default build):


{\small
\begin{verbatim}
HERE ARE THE UNIT TEST RESULTS:

Solved problem avion2.osil with Ipopt
Solved problem HS071.osil with Ipopt
Solved problem rosenbrockmod.osil with Ipopt
Solved problem parincQuadratic.osil with Ipopt
Solved problem parincLinear.osil with Ipopt
Solved problem callBack.osil with Ipopt
Solved problem callBackRowMajor.osil with Ipopt
Solved problem parincLinear.osil with Clp
Solved problem p0033.osil with Cbc
Solved problem rosenbrockmod.osil with Knitro
Solved problem callBackTest.osil with Knitro
Solved problem parincQuadratic.osil with Knitro
Solved problem HS071_NLP.osil with Knitro
Solved problem p0033.osil with SYMPHONY
Solved problem parincLinear.osil with DyLP
Solved problem volumeTest.osil with Vol
Solved problem p0033.osil with GLPK
Solved problem lindoapiaddins.osil with Lindo
Solved problem rosenbrockmod.osil with Lindo
Solved problem parincQuadratic.osil with Lindo
Solved problem wayneQuadratic.osil with Lindo
Test the MPS -> OSiL converter on parinc.mps using Cbc
Test the AMPL nl -> OSiL converter on hs71.nl using LINDO
Test a problem written in b64 and then converted to OSInstance
Successful test of OSiL parser on problem parincLinear.osil
Successful test of OSrL parser on problem parincLinear.osrl
Successful test of prefix and postfix conversion routines on problem rosenbrockmod.osil
Successful test of all of the nonlinear operators on file testOperators.osil
Successful test of AD gradient and Hessian calculations on problem CppADTestLag.osil

All tests completed successfully
\end{verbatim}
}
\else
Depending upon which third-party software you have installed, the result of running the {\tt unitTest}\index{OS project!unit test}
should look
something like (we have included the third-party solver LINDO\index{LINDO} in the test results below; it is not
part of the default build):


{\small
\begin{verbatim}
HERE ARE THE UNIT TEST RESULTS:

Solved problem avion2.osil with Ipopt
Solved problem HS071.osil with Ipopt
Solved problem rosenbrockmod.osil with Ipopt
Solved problem parincQuadratic.osil with Ipopt
Solved problem parincLinear.osil with Ipopt
Solved problem callBack.osil with Ipopt
Solved problem callBackRowMajor.osil with Ipopt
Solved problem parincLinear.osil with Clp
Solved problem p0033.osil with Cbc
Solved problem p0033.osil with SYMPHONY
Solved problem parincLinear.osil with DyLP
Solved problem volumeTest.osil with Vol
Solved problem p0033.osil with GLPK
Solved problem lindoapiaddins.osil with Lindo
Solved problem rosenbrockmod.osil with Lindo
Solved problem parincQuadratic.osil with Lindo
Solved problem wayneQuadratic.osil with Lindo
Test the MPS -> OSiL converter on parinc.mps using Cbc
Test the AMPL nl -> OSiL converter on hs71.nl using LINDO
Test a problem written in b64 and then converted to OSInstance
Successful test of OSiL parser on problem parincLinear.osil
Successful test of OSrL parser on problem parincLinear.osrl
Successful test of prefix and postfix conversion routines on problem rosenbrockmod.osil
Successful test of all of the nonlinear operators on file testOperators.osil
Successful test of AD gradient and Hessian calculations on problem CppADTestLag.osil

All tests completed successfully
\end{verbatim}
}
\fi

If you do not see
\begin{verbatim}
All tests completed successfully
\end{verbatim}
then you have not passed the unitTest and hopefully some semi-intelligible error message was given.

\vskip 8pt

\item{}  Install the libraries and executables.

\index{make install@{\tt make install}}
\begin{verbatim}
make install
\end{verbatim}

This will install all of the libraries in the  {\tt lib} directory.  In particular, the main OS library
{\tt libOS}\index{LibOS@{\tt LibOS}}
along with the libraries of the other COIN-OR projects  that download with the OS project will get installed
in the {\tt lib} directory.  In addition the {\tt make install} command will install several executable programs 
in the {\tt bin} directory, depending on the parameters on the {\tt configure command}.  One of these binaries 
is {\tt OSSolverService}\index{OSSolverService@{\tt OSSolverService}} which is the main OS project executable.
This is described in Section~\ref{section:ossolverservice}. In addition 
{\tt Clp}\index{COIN-OR projects!Clp@{\tt Clp}},
{\tt Cbc}\index{COIN-OR projects!Cbc@{\tt Cbc}}, 
{\tt Ipopt}\index{COIN-OR projects!Ipopt@{\tt Ipopt}},
{\tt Bonmin}\index{COIN-OR projects!Bonmin@{\tt Bonmin}},
{\tt Couenne}\index{COIN-OR projects!Couenne@{\tt Couenne}}
and {\tt SYMPHONY}\index{COIN-OR projects!SYMPHONY@{\tt SYMPHONY}}
get installed  in the {\tt bin} directory.
Necessary header files are installed in the {\tt include} directory.   In this case, {\tt bin}, {\tt lib}
and {\tt include} are all subdirectories of where {\tt ./configure}\index{configure} is run.   
If the user wants these files
installed elsewhere, then {\tt configure} should specify the {\tt prefix} of these directories.  That is,


\begin{verbatim}
./configure  --prefix=prefixDirectory  COIN_SKIP_PROJECTS="Ipopt Bonmin"
\end{verbatim}
\index{COIN_SKIP_PROJECTS@{\tt COIN\_SKIP\_PROJECTS}}

For example, running

\begin{verbatim}
./configure  --prefix=/usr/local  COIN_SKIP_PROJECTS="Ipopt Bonmin"
\end{verbatim}

\noindent and then running {\tt make}\index{make@{\tt make}}
 and {\tt make install}\index{make install@{\tt make install}}
 will put the relevant files in

\begin{verbatim}
/usr/local/bin
/usr/local/include
/usr/local/lib
\end{verbatim}

\end{enumerate}

\vskip 8pt

{\bf Run an Example!}  If {\tt make test}\index{make test@{\tt make test}}
 works, proceed to Section~\ref{section:ossolverservice} 
to run the key executable, {\tt OSSolverService}\index{OSSolverService@{\tt OSSolverService}}.



\subsubdivision{Building the OS Project on Mac OS X}\label{section:unixmacbuilds}

When building OS on Mac OS X 10.5.x (Leopard)   it may be necessary  to add the following to the configure line


\begin{verbatim}
ADD_CXXFLAGS="-mmacosx-version-min=10.4" 
ADD_CFLAGS="-mmacosx-version-min=10.4" 
ADD_FFLAGS="-mmacosx-version-min=10.4"
LDFLAGS="-flat_namespace"
\end{verbatim}

Also, the Mac OS X operating system does not come configured with the gcc compiler. Users wanting to build the OS project on the Mac should do the following:

\begin{itemize}
\item Install the Xcode developer tools.  These are available on the install DVD that comes with the machine or at the Apple developer site. See

\url{http://developer.apple.com/technology/xcode.html}

\item Install a Fortran compiler.  We have had good luck with the GNU {\bf gfortran} compiler. Platform specific binaries for the various Mac platforms (Leopard and Tiger, Intel and Power PC) are obtained at

\url{http://hpc.sourceforge.net/}

We followed the instructions and installed the binary using the command


\begin{verbatim}
sudo tar -xvf gcc-bin.tar -C /
\end{verbatim}

\end{itemize}

We have also successfully used the fink project, see

\url{http://www.finkproject.org/}

to download and build gcc/g++/gfortran compilers from source code. 


\subdivision{Building the OS Project on Windows}\label{section:windowsinstall}

There are a number of options open to Windows users.   First, if you wish to work with source code\index{OS project!source code}
we recommend downloading  the svn client, TortoiseSVN\index{TortoiseSVN}.  (See Section~\ref{section:svn}.)  
With TortoiseSVN
in the Windows Explorer connect to the directory (e.g., COIN-OS) where you wish to put the OS code.
Right-click on the directory and select {\tt SVN Checkout}.   In the textbox, {\tt URL of Repository}
give the URL for the version of the OS project you wish to check out, e.g.,

\medskip
\noindent{\tt\UrlOsStable}.
\medskip

Also, if you plan to build any of the projects contained in {\tt ThirdParty}\index{Third-party software}
(e.g., ASL)\index{Third-party software!ASL} we recommend using {\tt wget}\index{wget@{\tt wget}}. 
(See Section~\ref{section:wget}.)


\subsubdivision{Microsoft Visual Studio (MSVS)} \label{section:msvs}

\index{Microsoft Visual Studio|(}%
Microsoft Visual Studio solution and project files are provided for users of Windows and the Microsoft Visual Studio IDE.
We currently support Versions 8 and~9. These versions are also sometimes referred to by their
(approximate) release dates, which is 2008 for Version~9 and 2005 for Version~8.   In addition there is
a free version of the Visual Studio IDE C++ compiler,  called Visual C++ Express Edition\index{C++ compiler}.

The following steps are necessary to build the OS project using the  Microsoft Visual Studio IDE.

\begin{enumerate}[Step 1.] \setcounter{enumi}{-1}
\item{} If the C++ compiler {\tt cl} is already
installed,  go to  to Step~\ref{enumerate:winbuild2}.

\item{} Download and install the Visual C++ Express Edition, which is available for free at Microsoft's web site.
Version~9 is at {\tt\UrlCl}.
This download contains the Microsoft {\tt cl} C++ compiler along with necessary libraries.

\item{} \label{enumerate:winbuild2} The part of the OS library responsible for communication with a remote server depends on some
underlying Windows socket header files and libraries. These files are part of the commercial for-pay version,
but are not included in the Visual C++ Express download. If you have the Express Edition, it is necessary
to also download and install the Windows Platform SDK\index{Windows Platform SDK}, which can be found at

\medskip
\noindent{\scriptsize\tt\UrlSdk}.
\medskip

\item{} In the COIN-OR/OS directory you will find the folder MSVisualStudio,
which contains root directories organized by the version of Visual Studio.
We currently provide solution files for Version~8 and Version~9.
Each contains the file {\tt OS.sln}\index{OS sln@{\tt OS.sln}} and project files
for building the unitTest\index{unitTest@{\tt unitTest}} ({\tt OSTest.vcproj}\index{OSTest.vcproj@{\tt OSTest.vcproj}}),
the OSSolverService ({\tt OSSolverService.vcproj}\index{OSSolverService.vcproj@{\tt OSSolverService.vcproj}}) and
the OS libraries
({\tt libOSCommon.vcproj}\index{libOSCommon.vcproj@{\tt libOSCommon.vcproj}} and
({\tt libOSSolvers.vcproj}\index{libOSSolvers.vcproj@{\tt libOSSolvers.vcproj}}).
The Microsoft Visual Studio files are automatically downloaded with an SVN\index{SVN} checkout.
They are also contained in the tarballs (see Section~\ref{section:getTarBalls}).

Open the solution file or the individual project files (for instance by double-clicking
on them in Windows Explorer)  and select Build from the menu bar.
%If you have ASL\index{Third-party software!ASL} (see Section~\ref{section:ASL}) downloaded,
%you can also build the {\tt OSAmplClient}\index{OSAmplClient@{\tt OSAmplClient}} (see Section~\ref{section:amplclient})
%by modifying the Configuration Manager\index{Microsoft Visual Studio!Configuration Manager} and selecting the
%two projects {\tt libOSnl2OSiL}\index{libOSnl2OSiL@{\tt libOSnl2OSiL}}
%and {\tt OSAmplClient}\index{OSAmplClient@{\tt OSAmplClient}},
%which by default are not included in the build.

\item{} Run the {\tt unitTest}\index{unitTest@{\tt unitTest}}. Connect to the directory {\tt COIN-OR/OS/test} and run 
either the release or debug version of the {\tt unitTest} executable.
\end{enumerate}

%The solution file for version~7 provides two configurations, {\tt Debug} and {\tt Release}.
%The former includes debug information, but both are configured without Ipopt
%(see Section~\ref{section:ipopt}) or any of the third-party software described in
%section~\ref{section:otherthirdparty}.
%The solution file {\tt OS.sln}\index{OS sln@{\tt OS.sln}} contains three configurations, 
%{\tt Debug}\index{Microsoft Visual Studio!{\tt Debug} configuration} and 
%{\tt Release}\index{Microsoft Visual Studio!{\tt Release} configuration}, 
%both of which are configured without {\tt Ipopt}, as well as 
%{\tt Release-Plus}\index{Microsoft Visual Studio!{\tt Release-Plus} configuration},
%which can be used to add {\tt Ipopt}\index{COIN-OR projects!Ipopt@{\tt Ipopt}}, 
%{\tt Bonmin}\index{COIN-OR projects!Bonmin@{\tt Bonmin}} and ASL\index{Third-party software!ASL}
%(see Section~\ref{section:ASL}). In order to build this configuration successfully,
%the user must first download and process additional third-party software\index{Third-party software} as explained in 
%sections \ref{section:ipopt-msvs} and~\ref{section:ASL}.

The solution file {\tt OS.sln}\index{OS sln@{\tt OS.sln}} contains two configurations, 
{\tt Debug}\index{Microsoft Visual Studio!{\tt Debug} configuration} and 
{\tt Release}\index{Microsoft Visual Studio!{\tt Release} configuration}, 
both of which are configured without {\tt Ipopt}.

\index{Microsoft Visual Studio|)}%


\subsubdivision{Visual Studio Examples Distribution}\label{section:vsexamples}

Many users will not be interested in actually building the OS project from source code.   At the link
{\tt\UrlOsWin} are  binaries for using the OS project.
There are also Visual Studio project files for building applications that use the precompiled OS libraries.
In particular, download and unpack the file

\begin{verbatim}
OS-version_number-VisualStudio.zip
\end{verbatim}
\index{file naming conventions}

This zip archive contains a  {\tt bin} directory that holds  the executable  {\tt OSSolverService.exe}.
The {\tt OSSolverService.exe} is configured to run, out-of-the-box,   the following solvers.

\begin{itemize}

\item Bonmin

\item Clp

\item Cbc

\item Couenne

\item DyLP

\item Ipopt

\item SYMPHONY

\item Vol

\end{itemize}
The libraries necessary to run these solvers are included in the download.  {\it No additional software is necessary
to solve models with these solvers!}   See Section~\ref{section:ossolverservice} for details on how to use the
{\tt OSSolverService.exe} executable for solving optimization problems.


The {\tt bin} directory also contains the {\tt OSAmplClient.exe} executable. If the user has a Windows version of AMPL,
then AMPL can be used to invoke all of the solvers mentioned above through the {\tt OSAmplClient}.  For details
see Section~\ref{section:amplclient}.



This zip archive also contains a  {\tt lib} directory that holds  libraries
for a number of COIN-OR projects, including OS. It is possible to build
customized optimization applications that link against these libraries.
We provide several examples that use various aspects of the OS project
in order to build customized applications. The Visual Studio example solution
file is named {\tt osExamples.sln} and is found in the folder
{\tt MSVisualStudioOSExamples}. The solution file {\tt osExamples.sln}
currently contains nine projects (examples). These are described in more
detail in Section~\ref{section:examples}.

\iffalse
\begin{itemize}

\item[]  {\bf addCuts --} this project illustrates the use of  the {\tt Cbc} and {\tt Cgl} projects.
A file ({\tt p0033.osil}) in OSiL format is used to create an OSInstance object. The linear programming relaxation
is solved. Then, Gomory, simple rounding, and knapsack cuts are added using {\tt Cgl}.  The model is then optimized
using {\tt Cbc}.



\item[]  {\bf algorithmicDiff --} this project illustrates the {\tt calculate()} method calls in the {\tt OSInstance} class.
These {\tt calculate()} calls are used to calculate function values, gradients, and Hessians. These methods make underlying
calls to the {\tt CppAD} project.


\item[]  {\bf instanceGenerator --}  this project shows  how to build an instance using the {\tt OSInstance} class.
A number of key nonlinear operators are illustrated.


\item[]  {\bf osRemoteTest --}  this project shows  how to call a remote solver using Web Services.
{\bf Windows usrs should note}
that this project links to {\tt wsock32.lib}, which is not part of the Visual Studio  Express Package.  It is necessary
to also download and install the Windows Platform SDK\index{Windows Platform SDK}, which can be found at

\medskip
\noindent{\scriptsize\tt\UrlSdk}. 
\medskip
\noindent See also Section~\ref{section:msvs}.

\item[] {\bf osModDemo --} this provides yet another illustration of how to build an optimization instance using the
{\tt OSInstance} class.  In addition, this project illustrates how to modify and in-memory instance.   Finally, this project  shows how to build solver objects and use the solver object to
optimize the problem. In this particular case, the {\tt Clp} solver is used.

\end{itemize}


In addition, in the zip archive there is a folder {\tt MSVisualStudioTemplate}. This project contains a simple
{\tt Hello World} demo in the code {\tt demoCode.cpp}. However, the
solution file configured to link with all
of the libraries in the {\tt lib} directory and pointing to all of the
header files in the {\tt include} directory.
The user can simply replace what is currently in {\tt demoCode.cpp} with his or her own code.
\fi




\subsubdivision{Cygwin}\label{section:cygwin}

{\tt Cygwin} provides a Unix emulation environment for Windows. It comes with numerous tools and libraries including the {\tt gcc} compilers. See {\tt www.cygwin.com}.   Cygwin can be used with the Gnu Compiler Collection ({\tt gcc}) or with the Microsoft {\tt cl} compiler.

\vskip 8pt

\index{Cygwin|(}{\bf Using Cygwin with {\tt gcc}:}  With Cygwin and the corresponding {\tt gcc} compiler the OS project
is built exactly as described in Section~\ref{section:unixbuilds}. If you previously downloaded Cygwin with
gnome make version 3.81-1,  you must obtain a fixed 3.81 version from {\tt\UrlCygwinMake}.
(See also
%the Cygwin mailing list postings \url{http://cygwin.com/ml/cygwin/2006-09/msg00315.html} and \url{http://cygwin.com/ml/cygwin/2006-09/msg00153.html}) and
the discussion at {\tt\UrlCoinCygwin}.)


\vskip 8pt

{\bf Using Cygwin with Microsoft {\tt cl}:}   Users who are extremely adventuresome and have an abundance  of free time on their hands may wish to use Cygwin with the Microsoft {\tt cl} compiler to build the OS project.   The following steps have led to a successful build.


\begin{enumerate}[Step 1:]
\item{}  Download {\tt Cygwin}  from {\tt\UrlCygwinSetup} and install.




\item{}  Download  Visual Studio Express C++ at  

{\tt\UrlCl}.


\item{}  The part of the OS library responsible for communication with a remote server depends on some
underlying Windows socket header files and libraries. Therefore it is necessary to also download and install
the Windows Platform SDK\index{Windows Platform SDK}. Download the necessary files at

{\scriptsize\tt\UrlSdk}

 and install.



\item{}  Set the Cygwin search path configuration. This is important.
This step is necessary to ensure that Cygwin   looks for compilers, linkers, etc in the correct order.  The right order of directories  is: MSVS command directories, Cygwin command directories, and finally Windows command directories.  This is illustrated below.

\begin{itemize}

 \item First, Cygwin should look in the Microsoft Visual Studio directories.
If a standard Visual Studio install is done, the following  should be part of the
Cygwin search path.

\begin{verbatim}
.
:/cygdrive/c/Program Files/Microsoft Visual Studio 8/Common7/IDE
:/cygdrive/c/Program Files/Microsoft Visual Studio 8/VC/bin
:/cygdrive/c/Program Files/Microsoft Visual Studio 8/Common7/Tools
:/cygdrive/c/Program Files/Microsoft Visual Studio 8/SDK/v2.0/Bin
:/cygdrive/c/Program Files/Microsoft Visual Studio 8/VC/vcpackages
:/cygdrive/c/WINDOWS/Microsoft.NET/Framework/v2.0.50727
\end{verbatim}

\item Second, Cygwin should next search its  command directories.  The following is typical of a standard install.

\begin{verbatim}
/bin:/usr/local/bin:/usr/bin:/bin:/usr/X11R6/bin
\end{verbatim}

\item Third, Cygwin should search the Windows specific command directories.  The following is typical.

{\scriptsize
\begin{verbatim}
:/cygdrive/c/WINDOWS/system32:/cygdrive/c/WINDOWS
:/cygdrive/c/WINDOWS/System32/Wbem:/cygdrive/c/Program Files/ATI Technologies/ATI Control Panel
:/cygdrive/c/Program Files/Common Files/Roxio Shared/DLLShared/
:/cygdrive/c/Program Files/QuickTime/QTSystem/:/cygdrive/c/Program Files/Microsoft SQL Server/90/Tools/bin/
:/cygdrive/c/Program Files/Microsoft Platform SDK for Windows Server 2003 R2/Bin/
:/cygdrive/c/Program Files/Microsoft Platform SDK for Windows Server 2003 R2/Bin/WinNT/
:/cygdrive/c/Program Files/SSH Communications Security/SSH Secure Shell
:/cygdrive/d/SSH
\end{verbatim}
}


\end{itemize}
Open the Cygwin shell and check the value of {\tt \$PATH}\index{PATH@{\tt \$PATH}}. If directories don't appear in an order described above,
then the {\tt \$PATH} value needs to be reset.

%\item{} This step is necessary only if you wish to build with the AMPL {\tt ASL} solver
%library\index{Third-party software!ASL}.
%Unfortunately, and we regret this, but at the time of this writing the working version of {\tt ASL} for cygwin/
%cl build is its trunk version. This means that it is necessary to download the trunk version separately
%and replace the release version we have distributed with the trunk version.  The URL for the trunk
%version is
%
%\begin{verbatim}
%co https://projects.coin-or.org/svn/BuildTools/ThirdParty/ASL/trunk  ASL
%\end{verbatim}





\item{} Build the OS project (or any COIN-OR project). If you wish to avoid the FORTRAN\index{Fortran} related issues you should
build without {\tt Ipopt}\index{COIN-OR projects!Ipopt@{\tt Ipopt}}, 
{\tt Bonmin}\index{COIN-OR projects!Bonmin@{\tt Bonmin}} and {\tt Couenne}\index{COIN-OR projects!Couenne@{\tt Couenne}}. 
Issue the following command in the project root.
\begin{verbatim}
./configure COIN_SKIP_PROJECTS="Ipopt Bonmin Couenne" --enable-doscompile=msvc
\end{verbatim}
\index{COIN_SKIP_PROJECTS@{\tt COIN\_SKIP\_PROJECTS}}

If you wish to build with {\tt Ipopt} or {\tt Bonmin} and {\tt Couenne}, which depend on it, 
then FORTRAN is required --- and Visual Studio does not ship with a FORTRAN compiler.
The following is a work-around. (See also Section~\ref{section:ipopt}.)

\begin{enumerate}[Step a.]

\item{}  Obtain one of the   Harwell Subroutine Library (HSL)\index{Third-party software!HSL} routines
{\tt ma27ad.f} or {\tt MA57ad.f}. See {\tt\UrlHsl}.  Put the Harwell code in the
directory {\tt ThirdParty/HSL}. (Note the case in the file names, which is relevant in a unix-like environment.)




\item{}  Follow the instructions for downloading and installing the {\tt f2c}\index{f2c@{\tt f2c}} compiler from Netlib.
The installation instructions for this are in the {\tt INSTALL} file in
\begin{verbatim}
BuildTools/compile_f2c
\end{verbatim}



\item{}  Run the configure script

\begin{verbatim}
 ./configure  --enable-doscompile=msvc
\end{verbatim}


\end{enumerate}


\end{enumerate}
\index{Cygwin|)}



\subsubdivision{MinGW} \label{section:mingw}


MinGW\index{MinGW} (Minimalist GNU for Windows) is a set of runtime headers to be used with the GNU {\tt gcc} compilers for Windows.
See \url{www.mingw.org}. As with Cygwin, the OS project is  built exactly as described in Section~\ref{section:unixbuilds}.

The MinGW installation includes the {\tt gcc} compiler, which can interact negatively with the Microsoft {\tt cl} compiler.
For that reason it is advisable to download the even smaller installation MSYS (see next section) if you intend to
build any software with the Microsoft Visual Studio suite.

\vskip 8pt

{\bf Warning:} A user of  MSYS  with MinGW gcc version 4.4.0   got an error about a
missing library  ``pthreadsGC2.dll'' when running the OS {\tt unitTest.}  This user installed {\tt pthreadsGC2.dll} from
\begin{center}
 \url{ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/lib/pthreadGC2.dll}
\end{center}
and reported that the problem then went away.


\subsubdivision{MSYS} \label{section:msys}

\index{MSYS|(}%
MSYS (Minimal SYStem) provides an easy way to use the COIN-OS build system with compilers/linkers of your own choice,
such as the Microsoft command line C++ {\tt cl} compiler.  MSYS is intended as an alternative to the DOS command window.
It is an application that gives the user a Bourne shell that can run {\tt configure}  scripts and makefiles\index{makefile}.
No compilers come with MSYS.
In the Cygwin\index{Cygwin}, MinGW\index{MinGW}, and MSYS\index{MSYS} hierarchy, it is at the bottom of the food chain in terms of tools provided.
However, it is very easy to use and build the OS project with MSYS.    In this discussion we assume that the user
has downloaded the OS source code (most likely  with TortoiseSVN)\index{TortoiseSVN} 
and that the {\tt cl} compiler\index{cl compiler@{\tt cl} compiler} is present.
The project is built using the following steps.

\vskip 8pt

\noindent {\bf Note:}

\begin{itemize}

\item If you wish to use the third-party software with MSYS it is best to get {\tt wget}\index{wget@{\tt wget}}.
See Section~\ref{section:wget}.

 \item Do not put any imbedded blanks in the path to the OS project.
\end{itemize}



Execute the following steps to use the Microsoft C++ {\tt cl} compiler with MSYS.


\begin{enumerate}[Step 1.]

\item{} Download {\tt MSYS} at

{\noindent{\small\tt\UrlMingw}}

and install.  Double-clicking on the MSYS icon will open a Bourne shell window.

\item{}  Download  Visual Studio Express C++ at 

\noindent{\scriptsize\tt\UrlCl}

and install.

 \item{}  The part of the OS library responsible for communication with a remote server depends on some underlying
Windows socket header files and libraries. Therefore it is necessary to also download and install
the Windows Platform SDK\index{Windows Platform SDK}. Download the necessary files at

\noindent{\scriptsize\tt\UrlSdk}

 and install.

\item{}   Set the Visual Studio environment variables so that paths to the necessary libraries and header files  are recognized.  Assuming that a standard installation was done for the Visual Studio Express and the Windows Platform SDK set the variables as follows:

\begin{verbatim}
PATH=C:\Program Files\Microsoft Visual Studio 8\Common7\IDE;
C:\Program Files\Microsoft Visual Studio 8\VC\BIN;
C:\Program Files\Microsoft Visual Studio 8\Common7\Tools;
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin;
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727;
C:\Program Files\Microsoft Visual Studio 8\VC\VCPackages


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 Visual Studio 8\VC\LIB;
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib;
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib
\end{verbatim}

The environment variables can be set using the {\tt System Properties} in the Windows {\tt Control Panel}.


\item{}  In the MSYS command window connect to the root of the OS project and run the {\tt configure} 
script  followed by {\tt make}\index{make@{\tt make}}  as described in Section~\ref{section:unixbuilds}.

\end{enumerate}



{\bf Run an Example!}  If {\tt make test}\index{make test@{\tt make test}}
 works, proceed to Section~\ref{section:ossolverservice} to run the key executable, {\tt OSSolverService}.


Microsoft Windows users who wish to obtain MSYS for building the OS project can download
the appropriate software at {\tt \UrlMsys}.
The user may find this Web site confusing.
It is only necessary to download what is referred to as the {\bf MSYS Base System}.
As of this writing the most recent version is MSYS-\MsysVer.
This file is listed as {\tt \MsysFile} and the  binary download is

\noindent{\footnotesize\tt\UrlMsysBinary}

This will provide the necessary Bourne shell for executing the configure scripts.
Users who want to edit the source code in the parsers described in
Section~\ref{section:osparsers} will need the additional  tools
{\bf flex}\index{flex@{\tt flex}} and {\bf bison}\index{bison@{\tt bison}} 
as described in Section~\ref{section:flex}\index{MSYS|)}.



\subdivision{VPATH Installations} \label{section:vpath}

\index{VPATH|(}%
It is possible to build the OS project in a directory that is different from
the directory where the source code is present. This is called a {\tt VPATH}
compilation.  A {\tt VPATH}  compilation  is very useful if you wish to
build several versions (e.g., debug and non-debug versions, or versions with
availability of various combinations of third-party software) of the OS
project from a single copy of the source code.

For  example, assume you wish to build a debug version\index{debug version, MSYS|(} of the OS project in
the directory {\tt vpath-debug} and that {\tt ../COIN-OS} is the path to the
root of the OS project distribution.  Create the {\tt vpath-debug} directory,
leaving it empty for the moment.
From the {\tt vpath-debug} directory,
run {\tt configure} as follows:

\begin{verbatim}
../COIN-OS/configure --enable-debug
\end{verbatim}
%
After you run {\tt configure}, the OS distribution directory structure (see Figure~\ref{figure:osprojectrootdir})
will be mirrored in the {\tt vpath-debug} directory, and all of the necessary
{\tt Makefile}s\index{makefile|(} will be copied there.  Next from the {\tt vpath-debug} directory execute

\index{make@{\tt make}}
\begin{verbatim}
make
\end{verbatim}
%
and all of  the libraries created will be in their respective directories
inside {\tt vpath-debug} and not {\tt ../COIN-OS}.\index{debug version, MSYS|)}

\vskip 8pt
\noindent {\bf Notes:} 
\index{configure|(}
\begin{enumerate}
\item{} If you have already run the {\tt configure} script
inside the {\tt ../COIN-OS} directory, you cannot do a {\tt VPATH} build
until you have run
%
\index{make distclean@{\tt make distclean}}
\begin{verbatim}
make distclean
\end{verbatim}
%
in the {\tt ../COIN-OS} directory.

\item{}Note also that {\tt configure} automatically detects the presence of third-party software and prepares
the configuration and make files\index{makefile|)} accordingly. Once you have downloaded, 
e.g., Blas\index{Third-party software!Blas}, you must specify
%
\begin{verbatim}
configure COIN_SKIP_PROJECTS="ThirdParty/Blas"
\end{verbatim}
\index{COIN_SKIP_PROJECTS@{\tt COIN\_SKIP\_PROJECTS}}
%
if you want to recreate the default configuration.%
\index{VPATH|)}

\item{}If you work with the trunk\index{OS project!trunk version} version of OS, it is possible that files are added to
and removed from the distribution due to development activities. These files are not recognized properly
by the system unless it is reconfigured by running
%
\index{make distclean@{\tt make distclean}}
\begin{verbatim}
make distclean
\end{verbatim}
followed by 
\begin{verbatim}
./configure
\end{verbatim}
in the {\tt VPATH} directory.

\item{}You can customize compiler flags, linker options, include directories, and many other options by setting
appropriate environment variables. For further information you may want to consult the built-in help function by specifying
\begin{verbatim}
./configure --help
\end{verbatim}
or the help file available at the homepage of the {\tt BuildTools} project ({\UrlBuildtools}).
\end{enumerate}
\index{configure|)}


\subdivision{COIN-OR Projects Requiring Fortran}\label{section:ipopt}

\index{COIN-OR projects!Ipopt@{\tt Ipopt}|(}%
\index{COIN-OR projects!Bonmin@{\tt Bonmin}|(}%
\index{COIN-OR projects!Couenne@{\tt Couenne}|(}%
Ipopt, Bonmin and Couenne are COIN-OR projects 
(\url{http://projects.coin-or.org/Ipopt}, \url{http://projects.coin-or.org/Bonmin}, \url{http://projects.coin-or.org/Couenne})
and are included in the download with the OS project.
However, unlike the other COIN-OR projects that download with OS, these projects require third-party software
that is based on FORTRAN\index{Fortran} and is {\it not} part of the default distribution. Care must therefore be taken if
you wish to build OS with the Ipopt, Bonmin or Couenne solver. It is further important to know that there is a 
dependency between these three projects. Ipopt is the only one using Fortran directly, but Bonmin relies on Ipopt
for its solver, and Couenne is similarly dependent on both Ipopt and Bonmin. Neither Bonmin nor Couenne can therefore 
be installed in isolation.

You can exclude all three of these projects from the OS build by adding the option

\begin{verbatim}
COIN_SKIP_PROJECTS="Ipopt Bonmin Couenne"
\end{verbatim}
to the {\tt configure} script.

\ifipopt
\subsubdivision{Building Ipopt, Bonmin and Couenne in Unix or a Unix-like environment} \label{section:ipopt-unix}
If you are working in Unix or one of the Unix-like environments described in
section~\ref{section:windowsinstall}, you can proceed as follows.
\else
If you do choose to build {\tt Ipopt}, {\tt Bonmin} and {\tt Couenne}, it is best to work in Unix or one of the 
Unix-like environments described in Section~\ref{section:windowsinstall} (we recommend MSYS)\index{MSYS}.
\fi
To get the necessary third-party software\index{Third-party software}, first
connect into the {\tt ThirdParty} directory. Then execute the following commands:

\begin{verbatim}
$ cd Blas
$ ./get.Blas
$ cd ../Lapack
$ ./get.Lapack
$ cd ../Mumps
$ ./get.Mumps
\end{verbatim}



What you do next depends upon whether or not a FORTRAN\index{Fortran} compiler is present, and if so, which version
of FORTRAN.  There are several options. See also

%\begin{verbatim}
%http://www.coin-or.org/Ipopt/documentation/node13.html
%\end{verbatim}

\medskip
\noindent{\tt\UrlIpoptDocxiii}


\begin{enumerate}[{Option} 1.]

\item{}   If you \ifipopt\else are building in a Unix-like environment and \fi have a Fortran 95 compiler that
recognizes embedded preprocessor statements (such as {\tt gfortran} --- see~{\tt\UrlGfortran}
or {\tt g95} --- see~{\tt\UrlGgs}), you can simply run the {\tt configure} script and the FORTRAN
compiler will be detected and the {\tt Ipopt}, {\tt Bonmin} and {\tt Couenne} projects will be built.

\item{}   If your Fortran 95 compiler cannot deal with the preprocessor statements embedded in the
Mumps\index{Third-party software!Mumps} code, it may be possible to run the Fortran code through a preprocessor such as {\tt cpp}.
In the worst case you may have to resort to manual edits before you can build Ipopt --- or see 
Option~\ref{enumerate:ipopt3}.

\item{} \label{enumerate:ipopt3}
If you have a FORTRAN 77 compiler, you can replace Mumps by one of the Harwell Subroutine Library (HSL)%
\index{Third-party software!HSL} routines {\tt ma27ad.f} or {\tt MA57ad.f}. 
(Unix is case-sensitive, so note the file names carefully.) See

{\tt\UrlHsl}.  

You must obtain the Harwell code and put it in the directory {\tt \../ThirdParty/HSL}.  
Now run the {\tt configure}\index{configure} script as described in Section~\ref{section:unixbuilds}.

Note that the Harwell Subroutine Library is not governed by the Eclipse Public License\index{Eclipse Public License (EPL)}. It is the user's responsibility
to ensure adherence to appropriate copyright and distribution agreements.

\item{} \label{enumerate:ipopt4}
If you do not have a FORTRAN compiler and do not wish to obtain one, you can use the {\tt f2c}\index{f2c@{\tt f2c}}
translator from Netlib to translate HSL to {\tt C}.  The installation instructions for {\tt f2c}
are in the {\tt INSTALL} file in
\begin{verbatim}
BuildTools/compile_f2c
\end{verbatim}

\end{enumerate}

\noindent Two important points:


\begin{itemize}
\item Option~\ref{enumerate:ipopt4} also requires that one of the Harwell Subroutine Library (HSL) routines
{\tt ma27ad.f} or {\tt MA57ad.f} be present in the HSL directory.

\item If you run {\tt configure}\index{configure} with the {\tt --enable-debug} option on Windows, then when building the {\tt vcf2c.lib}, use the command line

\begin{verbatim}
CFLAGS = -MTd -DUSE_CLOCK -DMSDOS -DNO_ONEXIT
\end{verbatim}

\end{itemize}
\index{COIN-OR projects!Ipopt@{\tt Ipopt}|)}\index{COIN-OR projects!Bonmin@{\tt Bonmin}|)}%
\index{COIN-OR projects!Couenne@{\tt Couenne}|)}

\vskip 8pt

\ifipopt
\subsubdivision{Ipopt and Microsoft Visual Studio} \label{section:ipopt-msvs}

We regret that at present we cannot distribute a solution file
that can detect and reliably process the necessary third-party software to
build Ipopt. Users who need Ipopt on a Windows system are advised to download
the binary build as documented in Section~\ref{section:obtainingbinaries}.


\iffalse %------------------------------------------------------------------------
Users of Microsoft Visual Studio without access to a unix-like environment (Cygwin, MinGW or MSYS)
will have to prepare the third-party code after downloading. Since some of this code is written in Fortran,
you also need to obtain the {\tt f2c}\index{f2c@{\tt f2c}|(} Fortran to C translator. The steps are as follows.

\begin{enumerate}


\item{} From netlib, download the file

%\begin{verbatim}
%   http://www.netlib.org/f2c/libf2c.zip
%\end{verbatim}

{\tt\ \ \ \UrlFToCZip}

   and extract it in

\begin{verbatim}
   Ipopt\MSVisualStudio\v8
\end{verbatim}


 which is a folder in the root directory (see Figure~\ref{figure:osprojectrootdir}). Make sure that the files
are extracted into the subfolder {\tt libf2c} directly, instead of the subfolder {\tt libf2c$\tt\backslash$libf2c}.
One file created in this process should be

\begin{verbatim}
   Ipopt\MSVisualStudio\v8\libf2c\makefile.vc
\end{verbatim}


\item{} Open a Command Window (DOS prompt) and go into the directory

\begin{verbatim}
   Ipopt\MSVisualStudio\v8\libf2c\
\end{verbatim}

   Here, type

\begin{verbatim}
   nmake -f makefile.vc all
\end{verbatim}

   (If you see a problem related to the file {\tt comptry.bat}, edit the
   file {\tt makefile.vc} and just delete the line containing the one occurrence of
   '{\tt comptry.bat}'.)

Another possible error is that the system cannot find the header file {\tt unistd.h}.
If this occurs, add

\begin{verbatim}
-DNO_ISATTY
\end{verbatim}

at the end of line~9 of {\tt makefile.vc}.

\item{} Download the executable {\tt f2c.exe} from {\tt\UrlFToCBin}
and put it somewhere into your path
   (e.g., {\tt C:$\backslash$Windows})

\item{} Download the source code for Blas\index{Third-party software!Blas} (from {\tt\UrlBlas}),
Lapack\index{Third-party software!Lapack} (from {\tt\UrlLapack}),
and HSL\index{Third-party software!HSL} (see previous section).
Install each download into the appropriate subdirectory in {\tt ThirdParty}.

\item{} \label{enumerate:ipopt-step5}
In a DOS window, go to the directory

\begin{verbatim}
   Ipopt\MSVisualStudio\v8\libCoinBlas
\end{verbatim}

   and run the batch file

\begin{verbatim}
   convert_blas.bat
\end{verbatim}

   This runs the {\tt f2c} translator and generates new C files.%
\index{f2c@{\tt f2c}|)}


\item{} Repeat step~\ref{enumerate:ipopt-step5} in the directories

\begin{verbatim}
   Ipopt\MSVisualStudio\v8\libCoinLapack

   Ipopt\MSVisualStudio\v8\libCoinHSL
\end{verbatim}

   using the {\tt convert\_*.bat} files you find there.

\item{}
   Download the ASL\index{Third-party software!ASL} code and follow the steps in Section~\ref{section:ASL}.

\item{}
Now you can open the solution file

\begin{verbatim}
   OS\MSVisualStudio\v8\OS.sln
\end{verbatim}

and select the configuration {\tt Release-Plus}\index{Microsoft Visual Studio!{\tt Release-Plus} configuration}.
Open the Configuration Manager\index{Microsoft Visual Studio!Configuration Manager} (in the Build menu)
and set all projects to ``Build''
(by clicking the check-box next to the project name).
Then select Build (or press F7).
This will build all the necessary libraries for the
{\tt OSSolverService}\index{OSSolverService@{\tt OSSolverService}} executable
with the {\tt Ipopt} solver. The solution files for the {\tt Bonmin}\index{COIN-OR projects!Bonmin@{\tt Bonmin}} 
and {\tt Couenne}\index{COIN-OR projects!Couenne@{\tt Couenne}} solvers will be
available in a future release.

A {\tt unitTest}\index{unitTest@{\tt unitTest}},
the {\tt OSAmplClient}\index{OSAmplClient@{\tt OSAmplClient}} (see Section~\ref{section:amplclient})
and all the utility programs in Sections \ref{section:fileupload}
and~\ref{section:examples} are included in the build, as well.
\end{enumerate}

\fi     %------------------------------------ end of \iffalse
\fi     % end of \ifipopt


\subdivision{Other Third-Party Software} \label{section:otherthirdparty}

\index{Third-party software|(}%
This section deals with other third-party software not available for download at \url{www.coin-or.org}.
The OS project distribution includes the COIN-OR projects  {\tt Bonmin}\index{COIN-OR projects!Bonmin@{\tt Bonmin}},
{\tt Cbc}\index{COIN-OR projects!Cbc@{\tt Cbc}}, {\tt Clp}\index{COIN-OR projects!Clp@{\tt Clp}}, {\tt Cgl}\index{COIN-OR projects!Cgl@{\tt Cgl}},
{\tt CoinUtils}\index{COIN-OR projects!CoinUtils@{\tt CoinUtils}}, 
{\tt Couenne}\index{COIN-OR projects!Couenne@{\tt Couenne}}, {\tt CppAD}\index{COIN-OR projects!CppAD@{\tt CppAD}},
{\tt DyLP}\index{COIN-OR projects!DyLP@{\tt DyLP}},   {\tt Ipopt}\index{COIN-OR projects!Ipopt@{\tt Ipopt}},
{\tt Osi}\index{COIN-OR projects!Osi@{\tt Osi}}, {\tt SYMPHONY}\index{COIN-OR projects!SYMPHONY@{\tt SYMPHONY}}, and {\tt Vol}\index{COIN-OR projects!Vol@{\tt Vol}}.
(For details on any of these projects see the COIN-OR web site at {\tt\UrlCoinProjects}.)

However, the project is also designed to work with  several other open source and commercial software projects.
These are not distributed under the Eclipse Public Library and hence they cannot be downloaded
automatically by the system. 

For the open-source packages {\tt ASL}, {\tt Blas}, {\tt Lapack} and {\tt Mumps} --- a minimal set needed to build the Ipopt solver --- there are {\tt get.xxxx} scripts in the 
%In the OS distribution directory structure (see Figure~\ref{figure:osprojectrootdir}), there is a 
{\tt ThirdParty} directory  (see Figure~\ref{figure:osprojectrootdir}), which does not contain anything other than {\tt get.xxxx} scripts and other utilities.
The source code for any of these packages must be downloaded separately using the {\tt get.xxxx} scripts,
as {\tt configure}\index{configure|(} will not build these projects without the source code being present. After the download,
{\tt configure} will recognize the presence of these files in specific locations within the {\tt ThirdParty} folder hierarchy and will configure the makefiles\index{makefile} accordingly.

If the user wants to exclude these projects from the build after they have been downloaded and detected,
a new {\tt configure} is required with instructions to skip them. For instance, if the user experiences problems
with the Fortran\index{Fortran} compiler and its interaction with the system, the following command can be used
to skip all projects that use Fortran code:

\begin{verbatim}
configure COIN_SKIP_PROJECTS="Ipopt Bonmin Couenne ThirdParty/Blas ThirdParty/Lapack \
ThirdParty/Mumps"
\end{verbatim}
\index{COIN_SKIP_PROJECTS@{\tt COIN\_SKIP\_PROJECTS}}

Also in this class are the packages {\tt Metis}, a utility package that can optionally be used by 
{\tt Ipopt} to speed up computations, and {\tt Glpk}, a linear programming solver (see below). 

The last class of  external packages are commercial and closed-source programs, which may require special licenses, purchase agreements, and other  considerations which are strictly between the user and the third-party supplier. No {\tt get.xxxx} scripts are possible for these packages, and consequently it is hard to completely automate the build process. Nonetheless, it is possible to include these solvers, and we give below some indications as to how this might be accomplished.

In the {\tt inc} subdirectory of the {\tt OS}  directory, there is a header file, {\tt config\_os.h} that defines
the values of a number of
\index{COIN_HAS_XXXXX@{\tt COIN\_HAS\_XXXXX}|(}
\begin{verbatim}
COIN_HAS_XXXXX
\end{verbatim}
variables.

Many of the other header files contain {\tt \#include} statements inside {\tt  \#ifdef}  statements. For example,
\begin{verbatim}
#ifdef COIN_HAS_LINDO
#include "LindoSolver.h"
#endif
#ifdef COIN_HAS_GLPK
#include <OsiGlpkSolverInterface.hpp>
#endif
\end{verbatim}

If the project is configured with the simple {\tt ./configure} command given in Step~\ref{itemize:unixbuilds}
on page~\pageref{itemize:unixbuilds} with no arguments, then in the {\tt config\_os.h} header file the variables
associated with the third-party software described in this subsection will be undefined. For example:
\begin{verbatim}
/* Define to 1 if the Cplex package is used */
/* #undef COIN_HAS_CPX */
\end{verbatim}
unlike the configured COIN-OR projects that appear as
\begin{verbatim}
/* Define to 1 if the Clp package is used */
#define COIN_HAS_CLP 1
\end{verbatim}
In the following subsections we  describe how to incorporate various  third-party packages into the OS project
and see to it that the
\begin{verbatim}
COIN_HAS_XXXXX
\end{verbatim}
variable is defined in  {\tt config\_os.h}.
\index{COIN_HAS_XXXXX@{\tt COIN\_HAS\_XXXXX}|)}

\medskip
Make sure to run {\tt configure} after you have downloaded the required
source code, in order to modify the makefiles\index{makefile} appropriately. It is {\bf important to note} that even though there are
multiple files named {\tt configure} in various subdirectories, you should only ever run the master configure in the
distribution root directory, possibly accessed from a {\tt VPATH}\index{VPATH} as in Section~\ref{section:vpath}.
It sets important global variables and will call all other necessary configure files in turn.\index{configure|)}
You may also wish to view

{\small
%\begin{verbatim}
%https://projects.coin-or.org/BuildTools/wiki/user-configure#CommandLineArgumentsforconfigure
%\end{verbatim}
\noindent{\tt\UrlCoinConfigure}
}

\noindent for more information on command line arguments that are illustrated in the subsections below.%
\index{Third-party software|)}


\subsubdivision{AMPL Solver Library (ASL)} \label{section:ASL}

\index{Third-party software!ASL|(}%
The OS library contains a class, {\tt OSnl2osil}\index{OSnl2osil@{\tt OSnl2osil}} (see Section~\ref{section:nl2osil}),
and the program {\tt OSAmplClient}\index{OSAmplClient@{\tt OSAmplClient}} (see Section~\ref{section:amplclient}) that
require the use of the AMPL Solver Library~(ASL). See {\tt\UrlAmpl}  and  {\tt\UrlAmplSandia}.
Users with a Unix\index{Unix} system should locate the {\tt ASL} folder that is part of the distribution.
The {\tt ASL} folder is in the {\tt ThirdParty} folder
which is in the distribution root folder. Locate and execute the {\tt get.ASL} script.  Do this prior to running
the {\tt configure} script\index{configure}. The {\tt configure} script will then build the correct ASL library.

Microsoft  Visual Studio\index{Microsoft Visual Studio} users should note that {\tt OSAmplClient} is distributed 
as part of the binary distribution. For reasons explained in Section~\ref{section:ipopt-msvs} it is currently
not possible to distribute a solution file to let users build their own executable.

\iffalse %-----------------------------------------------------------------------------
Microsoft  Visual Studio\index{Microsoft Visual Studio} users will have to build the ASL library separately and
then link it with the OS library in the OS project file.  The necessary source files are at

%\begin{verbatim}
%http://netlib.sandia.gov/cgi-bin/netlib/netlibfiles.tar?filename=netlib/ampl/solvers
%\end{verbatim}

\noindent{\tt\UrlAmplSolvers}

After unpacking the distribution you will have to create the file
{\tt ThirdParty/ASL/details.c} by hand,
as follows: Copy the file {\tt details.c0} to {\tt details.c} and replace the
line
\begin{verbatim}
char sysdetails_ASL[] = "System_details";
\end{verbatim}
by
\vskip 8pt
\noindent{\tt char sysdetails\_ASL[] = "MS VC++ }$n${\tt .0";}
\vskip 8pt
\noindent
where $n$ is the version number of the {\tt cl} compiler on your system (most
likely 7, 8 or~9).

To avoid linker errors\index{linker errors} in MSVS, you may have to edit the file {\tt fpinitmt.c}.
Specifically, if you see the error ``multiply defined object \_matherr'', you must
hide the definition of {\tt \_matherr} in {\tt fpinitmt.c} and comment out lines 212--225
which read
\begin{verbatim}
 matherr_rettype
matherr( struct _exception *e )
{
	switch(e->type) {
	  case _DOMAIN:
	  case _SING:
		errno = set_errno(EDOM);
		break;
	  case _TLOSS:
	  case _OVERFLOW:
		errno = set_errno(ERANGE);
	  }
	return 0;
	}
\end{verbatim}

Then you must build the source code with the utility {\tt nmake}
which should be part of the Visual Studio distribution. (This can be done in a Command Window.)
The appropriate command is
\begin{verbatim}
nmake -f makefile.vc
\end{verbatim}
This produces the library file {\tt amplsolv.lib}, which is placed in the subfolder
{\tt ThirdParty$\tt\backslash$ASL$\tt\backslash$solvers}.

        
\ifipopt
Before you can use the {\tt Release-Plus}\index{Microsoft Visual Studio!{\tt Release-Plus} configuration} 
configuration in our solution file {\tt OS.sln}\index{OS sln@{\tt OS.sln}},
you must also prepare the source for the solver {\tt Ipopt}\index{COIN-OR projects!Ipopt@{\tt Ipopt}}
(see Section~\ref{section:ipopt-msvs}). If you want to add other third-party software or include debug information,
you may have to modify (or copy) this configuration and tailor it to your needs.
\else
Now you are ready to use MSVS. Both the {\tt Debug}\index{Microsoft Visual Studio!{\tt Debug} configuration} and 
{\tt Release}\index{Microsoft Visual Studio!{\tt Release} configuration} configurations contain two projects, 
{\tt libOSnl2OSiL} and {\tt OSAmplClient}, which use the ASL library and are normally deactivated. 
Activate these projects in the Configuration Manager\index{Microsoft Visual Studio!Configuration Manager} 
(available from the Build menu), then select Build.
%If you want to add other third-party software or include debug information, you may have to modify
%(or copy) this configuration and tailor it to your needs.
\fi
\fi
\index{Third-party software!ASL|)}

\subsubdivision{GLPK}

\index{Third-party software!GLPK|(}%
{\tt GLPK} is an open-source linear and integer-programming solver from the GNU organization. See {\tt\UrlGlpk}. 
GLPK is distributed under the GNU General Public Licence (GPL)\index{GNU General Public Licence (GPL)}, which is 
incompatible with the Eclipse Public License (EPL)\index{Eclipse Public License (EPL)} that governs OS. 
For that reason we are unable to distribute OS binaries linked to the GLPK solver.  
Users interested in GLPK must build OS from source and link to the GLPK libraries.

In order to use GLPK with OS in a unix environment, connect to {\tt
ThirdParty/Glpk} and execute {\tt get.Glpk}. Once the source code has been downloaded, run {\tt configure}, 
followed by a {\tt make}, as explained in Section~\ref{section:unixbuilds} or 
Section~\ref{section:vpath}.

Users on MSVS\index{Microsoft Visual Studio} can download the source by
anonymous {\tt ftp} from
\begin{verbatim}
ftp://ftp.gnu.org/gnu/glpk/glpk-version_number.tar.gz
\end{verbatim}

At the time of this writing, the most up-to-date version is \GlpkVer, which can be found at
%\begin{verbatim}
%ftp://ftp.gnu.org/gnu/glpk/glpk-4.30.tar.gz
%\end{verbatim}
\noindent{\tt\UrlGlpkDownload}
\index{Third-party software!GLPK|)}


\subsubdivision{SoPlex}

\index{Third-party software!SoPlex|(}%
{\tt SoPlex} was developed at the
Konrad-Zuse-Zentrum f\"ur Informationstechnik Berlin
and is available in source code. 
SoPlex is free for academic research and can be licensed for commercial use. 

Because of the licensing arrangement we are not able to provide {\tt get.soplex} scripts. Rather, each prospective user will have to download their own code from 

\noindent{\tt\UrlSoPlexDownload}.

There is no specific location where the source should be installed, but when the {\tt configure} script is run it is important to indicate where the required header and library files are found, for instance: 

\begin{verbatim}
configure --with-soplex-lib="-L$(HOME)/Soplex/soplex-1.7.1/lib -lsoplex"      \
--with-cplex-incdir="$(HOME)/Soplex/soplex-1.7.1/src"
\end{verbatim}
\index{Third-party software!SoPlex|)}%

\subsubdivision{Cplex} \label{section:Cplex}

\index{cplex@{\tt cplex}|(}%
Cplex is a linear, integer, and quadratic solver. See {\tt\UrlCplex}.
Cplex does not provide source code and you can only download the platform dependent binaries.
After installing the binaries and include files in an appropriate directory, run {\tt configure} to point to the
include and library directory. An example is given below:

\begin{verbatim}
configure --with-cplex-lib="-L$(HOME)/Cplex/cplex/lib -lcplex -lilocplex -lm -lpthread"   \
--with-cplex-incdir="$(HOME)/Cplex/cplex/include"
\end{verbatim}

You may also need the following environment variables (if they are not already set). The following  values were used in a working implementation.
\begin{verbatim}
LD_LIBRARY_PATH=$(LD_LIBRARY_PATH):$(HOME)/Cplex/cplex/lib
ILOG_LICENSE_FILE="$(HOME)/Cplex/cplex/access.ilm
%PATH=***:/usr/local/ilog/cplex81/bin/i86_linux2_glibc2.3_gcc3.2:***
%CLASSPATH=:/usr/local/ilog/cplex81/bin/i86_linux2_glibc2.3_gcc3.2:
\end{verbatim}
\index{cplex@{\tt cplex}|)}

\subsubdivision{Gurobi}

\index{Gurobi|(}%
Like {\tt cplex}, Gurobi is a commercial code that solves linear, integer and quadratic programs.
See {\tt\UrlGurobi}. Gurobi needs to be downloaded and installed similarly to {\tt cplex}, using directives on the {\tt configure} command as to where the library and header files are to be found, for example

\begin{verbatim}
configure --with-gurobi-lib="-L$(HOME)/gurobi/lib -lgurobi55 -lpthread -lm"    \
--with-gurobi-incdir="$(HOME)/gurobi/include"
\end{verbatim}

In addition it is necessary to set the environment variables {\tt LD\_LIBRARY\_PATH} and {\tt GRB\_LICENSE\_FILE} to point to the location of the libraries and the license file, e.g.,

\begin{verbatim}
LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:$(HOME)/Cplex/cplex/lib
GRB_LICENSE_FILE='$(HOME)/gurobi/gurobi.lic'
\end{verbatim}

\noindent{\bf Remark.} If both {\tt cplex} (see Section \ref{section:Cplex}) and Gurobi are to be 
linked to OS, file locations for both programs must be added to the {\tt configure} command, as follows:

\begin{verbatim}
configure --with-cplex-lib="-L$(HOME)/Cplex/cplex/lib -lcplex -lilocplex -lm -lpthread""  \
--with-gurobi-lib="-L$(HOME)/gurobi/lib -lgurobi55 -lpthread -lm"    \
--with-cplex-incdir= $(HOME)/Cplex/cplex/include  --with-gurobi-incdir="$(HOME)/gurobi/include" 
\end{verbatim}
  
\index{Gurobi|)}%

\subsubdivision{Mosek}% and Xpress}

\index{Mosek|(}%
%\index{Xpress|(}%

In the same way another commercial LP and IP solver, Mosek (see {\tt\UrlMosek})
% and Xpress (see {\small\tt\UrlXpress})
, can be hooked to OS. The relevant information to add to the {\tt configure} command is

\begin{verbatim}
--with-mosek-lib="-L$(HOME)/$(MOSEK)/bin -lmosek64 -liomp5 -lpthread -lm"    \
--with-mosek-incdir="$(HOME)/$(MOSEK)/include"                          \
\end{verbatim}
%--with-xpress-lib="-L$(HOME)/$(XPRESS)/lib -lgurobi55 -lpthread -lm"    \
%--with-xpress-incdir="$(HOME)/$(XPRESS)/include"                          

with appropriate information for the environment variable {\tt MOSEK} %and {\tt XPRESS} 
to point to the correct file locations for the Mosek %and Xpress 
header files and libraries.
\index{Mosek|)}%
%\index{Xpress|)}%


\ifknitro
\subsubdivision{Knitro}

\index{Knitro|(}%
Knitro is a nonlinear solver. See {\tt\UrlKnitro}.  Ziena does not provide source code for Knitro.  You must download platform dependent binaries.   In order to use Knitro with the OS project, perform the following steps.

\begin{enumerate}[Step 1:]

\item{}  Download {\tt knitro} to the desired directory.

\item{}  Copy the file {\tt nlpProblemDef.h} from the {\tt examples/C++} directory to the {\tt include} directory.

\item{}  Edit the file {\tt nlpProblemDef.h} and delete the following lines:

\begin{verbatim}
NlpProblemDef::~NlpProblemDef (void)
{
    //---- DO NOTHING.
    return;
}
\end{verbatim}

\item{} Run {\tt configure} with appropriate values for  {\tt --with-knitro-lib} and {\tt --with-knitro-incdir}.
For example:

\begin{verbatim}
configure --with-knitro-lib="-L/home/kmartin/files/code/knitro/linux/lib -lknitro "
--with-knitro-incdir=/home/kmartin/files/code/knitro/linux/include
\end{verbatim}

\end{enumerate}
\index{Knitro|)}
\fi

\subsubdivision{LINDO}

\index{LINDO|(}%
LINDO is a commercial linear, integer, and nonlinear solver. See \url{http://www.lindo.com}.
LINDO does not provide source code and you can only download the platform dependent binaries.
After installing the binaries and include files in an appropriate directory, run {\tt configure} to point to the
include and library directory. An example is given below:

\begin{verbatim}
configure --with-lindo-incdir=/home/kmartin/files/code/lindo/linux/include
--with-lindo-lib="-L/home/kmartin/files/code/lindo/linux/lib -llindo -lmosek"
\end{verbatim}
\index{LINDO|)}

\subsubdivision{MATLAB}

\index{MATLAB|(}%
MATLAB is a commercial programing environment especially suited for the development and testing of 
computationally intensive tasks. (See \url{http://www.mathworks.com/products/matlab}.)
Install MATLAB on the client machine and follow the instruction in Section~\ref{section:usingmatlab}.%
\index{MATLAB|)}

\subsubdivision{Library Paths}

After running {\tt configure} as described above,  on Unix systems, it will be necessary to set the
environment variables {\tt LD\_LIBRARY\_PATH} or {\tt DYLD\_LIBRARY\_PATH} (on Mac OS X) to point to the
location of the installed third-party libraries in the case that the libraries are dynamic and not static libraries.


\subdivision{Bug Reporting}

Bug reporting\index{Bug reporting} is done through the project Trac\index{Trac system} page. This is at
%\begin{verbatim}
%http://projects.coin-or.org/OS
%\end{verbatim}

\medskip
\noindent{\tt\UrlTrac}
\medskip

To report a bug, you must be a registered user.  For  instructions on  how to register, go to
%\begin{verbatim}
%http://www.coin-or.org/usingTrac.html
%\end{verbatim}

\medskip
\noindent{\tt\UrlUsingTrac}
\medskip

After registering, log in and then file a trouble ticket by going to
%\begin{verbatim}
%http://projects.coin-or.org/OS/newticket
%\end{verbatim}

\medskip
\noindent{\tt\UrlNewticket}
\medskip


\subdivision{Documentation}\label{section:documentation}

\index{Doxygen|(}%
If you have Doxygen  (\url{http://www.doxygen.org}) available (the executable {\tt doxygen} should be in the {\tt path} command) 
then executing
\begin{verbatim}
make doxydoc
\end{verbatim}
in the project root directory will result in the Doxygen documentation being generated and stored in the {\tt doxydoc} 
folder in the project root.

In order to view the documentation, open a browser and open the file
\begin{verbatim}
projectroot/doxydoc/html/index.html
\end{verbatim}

By default, running Doxygen will generate documentation for only the  OS project.  Documentation will not be generated 
for the other COIN-OR projects in the project root. In the {\tt doxydoc}  folder is a configuration file 
{\tt doxygen.conf}.  This configuration file contains the {\tt EXCLUDE} parameter

\begin{verbatim}
EXCLUDE =  Bonmin \
   Cbc\
   Cgl \
   Clp \
   CoinUtils \
   Couenne \
   cppad \
   SYMPHONY \
   Vol \
   DyLP \
   ThirdParty \
   Osi \
   include
\end{verbatim}

This file can be edited, and any project for which documentation is desired, can be deleted from the {\tt EXCLUDE} list.%
\index{Doxygen|)}





\subdivision{Platforms}

The build process described in Section~\ref{section:unixbuilds} has been tested on Linux\index{Linux}\index{Unix},
Mac OS X\index{Mac OS X}, and on Windows using  MinGW/MSYS\index{MinGW}\index{MSYS} and Cygwin\index{Cygwin}.
The  {\tt gcc}/{\tt g++} and Microsoft {\tt cl} compiler have been tested.
A number of solvers have also been tested with the OS library. For a list of tested solvers and platforms see
Table~\ref{table:testedplatforms}.  More detail on the platforms listed in Table~\ref{table:testedplatforms}
is given in Table~\ref{table:platformdescription}.  For a list of other  platforms testing the OS project see 

\medskip
\noindent{\tt\UrlNightlyBuild}.
\medskip

\begin{table}
\caption{Tested Platforms for Solvers}
\centering
\label{table:testedplatforms}
\vskip 8pt
 \begin{tabular}{l|c|c|c|c|c|c|}
 &Mac&Linux&Cyg-gcc&Msys-cl&MinGW-gcc&MSVS \\ \hline
Bonmin       &x&x&x&x&x&x \\ \hline
Cbc          &x&x&x&x&x&x \\ \hline
Cgl          &x&x&x&x&x&x \\ \hline
Clp          &x&x&x&x&x&x \\ \hline
Couenne      &x&x& &x&x&  \\ \hline
Cplex        & &x& & & &  \\ \hline
DyLP         &x&x&x&x&x&x \\ \hline
Glpk         &x&x&x&x&x&  \\ \hline
Ipopt        &x&x&x&x&x&x \\ \hline
\ifknitro
Knitro       &x&x& & & &  \\ \hline
\fi
Lindo        &x&x& &x& &x \\ \hline
MATLAB       &x& & & & &  \\ \hline
OSAmplClient &x&x& &x& &x \\ \hline
SYMPHONY     &x&x&x&x&x&x \\ \hline
Vol          &x&x&x&x&x&x \\ \hline
\end{tabular}
\end{table}


 \begin{table}
\caption{Platform Description}
\centering
\label{table:platformdescription}
\vskip 8pt
 \begin{tabular}{l|c|c|c|}
 & {\bf Operating System} & {\bf Compiler} & {\bf  Hardware} \\ \hline
 Mac &Mac OS X 10.4.9&gcc 4.0.1&Power PC \\   \hline
  Mac &Mac OS X 10.4.10&gcc 4.0.1&Intel \\   \hline
 Linux &Ubuntu  7.10 &gcc 4.1.2& Dell Intel 32 bit chip\\ \hline
 Cyg-gcc &Windows 2003 Server&gcc 4.2.2& Dell Intel 32 bit chip \\ \hline
 Msys-cl &Windows XP&cl 14.00 &Dell Intel 32 bit chip \\ \hline
 MinGW-gcc &Windows XP&gcc 3.4.2&Dell Intel 32 bit chip \\ \hline
 MSVS &Windows XP&Visual Studio 8 and 9 &Dell Intel 32 bit chip \\ \hline
\end{tabular}
\end{table}
