# source:stable/5.1/SYMPHONY/Doc/man-start.tex@900

Last change on this file since 900 was 900, checked in by tkr, 7 years ago

Merging revision 899 into stable/5.1

• Property svn:eol-style set to native
• Property svn:keywords set to Author Date Id Revision
File size: 34.4 KB
Line
1%===========================================================================%
2%                                                                           %
3% This file is part of the documentation for the SYMPHONY MILP Solver.      %
4%                                                                           %
5% SYMPHONY was jointly developed by Ted Ralphs (tkralphs@lehigh.edu) and    %
7%                                                                           %
9%                                                                           %
11% accompanying file for terms.                                              %
12%                                                                           %
13%===========================================================================%
14
15This chapter is concerned with detailed instructions for building and
16installing SYMPHONY, along with its associated libraries and applications.
17
18\section{Installing the Binary Distribution}
19
20For the users who only need the generic MILP solver or the SYMPHONY callable
21library to be used in their custom applications, there are binary
22distributions released for different compilers and platforms. Each
23distribution consists of an executable and libraries built from the source
24code of SYMPHONY version \VER. It is important to note, however, that the
25pre-compiled binaries are missing some very useful functionality because of
26the fact that we are unable to distribute code linked to libraries licensed
27under the GNU General Public License (GPL). There are also a number of other
28potentially useful configurations (such as the parallel version) that we do not
29distribute in binary form. Building from source should be easy in most
30environments and will give you more flexibility. See
32functionality available when building from source.
33
34You can obtain the SYMPHONY binary distribution by visiting
35{\color{Brown}
36\begin{verbatim}
38\end{verbatim}
39}
40The binaries are currently available for Linux and Windows. These binaries are
41built with the following default options:
42\begin{itemize}
43\item The associated LP solver is the COIN LP solver (CLP).
44\item Cut generation is done with COIN's Cut Generation Library (CGL).
45\item All libraries are compiled statically.
46%\item Library linked with = CLP, CGL, COINUTILS, OSI, OSICLP, OSISYM,
47\item The optimization level for Linux binaries is O2''.
48\item Only serial executables are included.
49\end{itemize}
50
51\subsection{Installation in Unix-like environments}
52\label{building-unix}
53
54\begin{itemize}
55\item Unpack the distribution with
56{\color{Brown}
57\begin{verbatim}
58 tar xzvf symphony-\VER-XXX-bin.tgz
59\end{verbatim}
60}
61where \code{XXX} indicates the platform and the version of
62compiler used to build the distribution.
63Switch into the root directory of the unpacked distribution.
64
65\item First, test the executable by going to the \code{bin} directory and
66typing
67{\color{Brown}
68\begin{verbatim}
69 ./symphony -F ../examples/sample.mps
70\end{verbatim}
71}
72\item To test the callable library, the distribution
73includes sample files in \code{examples} directory:  \\ \\
74\code{milp.c}: This sample code is an implementation of a basic MILP
75solver using SYMPHONY's C callable functions with user defined input (see
76Section
77\ref{callable_library}). To test the code, go to the \code{examples} directory
78and type
79{\color{Brown}
80\begin{verbatim}
81 make milp
82 milp
83 \end{verbatim}}
84\code{milpOsi.c}: This sample code is an implementation of a basic MILP
85solver using SYMPHONY's C++ callable functions (through OsiSym interface)
86with user defined input (see Section \ref{OSI}). To test the code,
87go to \code{examples} directory and type,
88{\color{Brown}
89\begin{verbatim}
90 make milpOsi
91 milpOsi
92 \end{verbatim}}
93\end{itemize}
94
95If everything is working properly, the libraries, executables and header files
96can be installed in appropriate system directories if desired. This must be
97done by hand. This step will be done automatically if building from source
98using the automatic scripts provided (see below).
99
100\subsection{Installation for Use With Microsoft Visual C++}
101
102These instructions are for use with Microsoft Visual Studio 6.0. The procedure
103for other version of Visual Studio should be similar. Download and unpack the
104archive \code{symphony-\VER-win32-msvc6.zip}
105\begin{itemize}
106\item First, test the executable by opening Windows Explorer and double-click
107on {\color{Brown}\texttt{symphony.exe}} in the {\color{Brown}\texttt{bin}}
108directory in the folder in which the distribution was unpacked. This should
109open a Window in which the interactive solver will appear. Type \code{help}
110or \code{?} to see a list of available commands or see Chapter
111\ref{API-overview} for instructions on using the interactive solver.
112
113\item To test the callable library, the distribution includes sample codes
114along with associated project files in the \code{examples} directory. \\ \\
115\code{milp.c}: This sample code is an implementation of a basic MILP
116solver using SYMPHONY's C callable functions with user defined input (see
117Section \ref{callable_library}). To test the code, either
118
119\begin{itemize}
120\item open the workspace \code{milp.dsw}, choose \code{Build milp.exe}
121and then choose \code{Execute} from the \code{Build} menu,
122\end{itemize}
123or
124\begin{itemize}
125\item open a command terminal (choose \code{Run} on the Start menu and type
126\code{cmd} in the dialogue box) and type
127{\color{Brown}
128\begin{verbatim}
129 devenv milp.sln /make "all - debug"
130 Debug/milp.exe
131 \end{verbatim}
132}
133\end{itemize}
134\code{milpOsi.c}: This sample code is an implementation of a basic MILP
135solver using SYMPHONY's C++ callable functions (through OsiSym interface)
136with user defined input (see Section \ref{OSI}). To test the code, either
137\begin{itemize}
138\item open the workspace \code{milpOsi.dsw},
139choose \code{Build milpOsi.exe} and then
140\code{Execute} commands from the \code{Build} menu,
141\end{itemize}
142or
143\begin{itemize}
144\item open a command terminal (choose \code{Run} on the Start menu and type
145\code{cmd} in the dialogue box) and type
146{\color{Brown}
147\begin{verbatim}
148 devenv milpOsi.slb /make "all - debug"
149 Debug/milpOsi.exe
150 \end{verbatim}
151}
152\end{itemize}
153\end{itemize}
154
155% Applications????
156
157%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
158
159\section{Building From Source}
160\label{building_from_source}
161
162SYMPHONY can now use the COIN-OR build system and the GNU autotools to
163automate the build process. The build process should therefore be identical in
164all Unix-like environments. It is even possible to use this system to build
165COIN in Windows using the Microsoft Visual C++ compiler if you have MinGW
166(\url{http://www.mingw.org}) installed (you need the GNU \code{make} command).
167The instructions below will lead you through the steps required to compile
168SYMPHONY as a generic MILP solver. This process will create (1) a generic
169callable library that allows SYMPHONY to be called from a C or C++ code and
170(2) an executable that can be used as a stand-alone application to solve MILPs
171written in either MPS or GMPL file format. SYMPHONY can be further customized
172by implementing one of more than 50 callback functions that change SYMPHONY's
173default behavior. For information on customizing SYMPHONY using callbacks, a
174quick start guide is provided below. More detailed information is provided in
175Chapter~\ref{SYMPHONY-development}.
176
177\subsection{External Dependencies}
178
179\paragraph{The LP Engine.} SYMPHONY requires the use of a third-party
180  callable library to solve the LP relaxations once they are formulated. The
181LP solver is called through Open Solver Interface, also available from
183\begin{latexonly}
184(\texttt{https://projects.coin-or.org/Osi})
185\end{latexonly}.
186The list of solvers with OSI interfaces currently numbers eight and includes
187both commercial and open source alternatives. By default, SYMPHONY now uses
188the COIN LP solver (Clp). However, if another LP solver is desired, this is
189possible by changing the configuration settings.
190
191\paragraph{GMPL Parser.} If you would like to be able to parse GMPL models
192(GMPL is a subset of AMPL), you will need to install GLPK
193(\url{http://www.gnu.org/software/glpk/}) and configure SYMPHONY appropriately
194(see below).
195
196\paragraph{COIN Libraries.} SYMPHONY uses other COIN libraries for certain
197functionality, such as parsing MPS files, solving linear programs, generating
198valid inequalities, and for general matrix utilities. The libraries required
199for this functionality are now included with the distribution.
200
201\paragraph{GNU Libraries.} If the \code{readline} and \code{history} libraries
202are available, the interactive solver will have command history and command
203completion available. This functionality is only available in Unix-like
204environments by configuring with the \code{--enable-gnu-packages} option (see
205below).
206
207\subsection{Building in Unix-like environments}
208\label{getting_started_unix}
209
211
212You can obtain the SYMPHONY source code either via the subversion repository
213or in the form of archived releases. The recommended method in Unix is to use
214subversion because it makes it easier to obtain updates. In a Unix-like
215environment (such as Linux or CYGWIN), the following command may be used to
216obtain SYMPHONY from source using SVN in most cases: {\color{Brown}
217\begin{verbatim}
218 svn checkout https://projects.coin-or.org/svn/SYMPHONY/stable/5.1 SYMPHONY-5.1
219\end{verbatim}
220}
221Alternatively, you can get point releases of the source code as a compressed
222file by visiting
223{\color{Brown}
224\begin{verbatim}
226\end{verbatim}
227}
229{\color{Brown}\texttt{SYMPHONY-\VER.tgz}} and unpack the distribution with
230{\color{Brown}
231\begin{verbatim}
232 tar -xzf SYMPHONY-5.1.1.tgz
233\end{verbatim}
234}
235This will create a subdirectory called \code{SYMPHONY-\VER} containing
236the distribution.
237
238\subsubsection{Configuring}\label{configuring}
239
240The first step is to run a configuration script that will allow the
241compilation process to be customized for your environment. to perform this
242step, switch into the root directory of the distribution and type
243{\color{Brown}
244\begin{verbatim}
245 ./configure
246\end{verbatim}
247} This will set up the default configuration files. If you want to override
248the default settings, you can either run the configuration script with
249command-line options or else modify the options in the file
250{\color{Brown}\texttt{share/config.site}}. A complete list of options with
251brief explanations can be seen both in the file
252{\color{Brown}\texttt{share/config.site}} and by typing
253{\color{Brown}
254\begin{verbatim}
255 ./configure --help=recursive
256\end{verbatim}
257}
258See Figure \ref{conf_opts} for a list of options the user may want to set.
259
260\begin{figure}[htb]
261\begin{tabular}{ll}
262\hline
263\texttt{--enable-debug} & compile all projects with debug options set \\
264\texttt{--enable-debug-symphony} & compile only SYMPHONY project with debug options \\
265\texttt{--enable-static} & build static libraries \\
266\texttt{--enable-static-executable} &  create a complete static executable \\
267\texttt{--enable-gnu-packages} & compile with GNU packages \\
268& compile interactive optimizer with readline library \\
269\hline
270\texttt{--disable-cgl-cuts} & disable generic cut generation \\
271\texttt{--enable-sensitivity-analysis} & compile in the sensitivity analysis features \\
272\texttt{--enable-root-only} & process only the root node \\
273\texttt{--enable-frac-branching} & compile in the fractional branching option \\
274\texttt{--enable-tests}&  perform additional sanity checks (for debugging purposes) \\
275\texttt{--enable-tm-tests }& perform more tests  \\
279\texttt{--enable-pseudo-costs}& enable some experimental pseudo-cost branching tools \\
280\texttt{--enable-draw-graph} &  enable IGD graph drawing application \\
281\hline
282\texttt{ --with-XXX-incdir} &  specify the directory with the header files for the XXX package \\
283&where XXX is one of LP solver packages: cplex, glpk, osl, soplex, \\
284& xpress \\
285\texttt{--with-XXX-lib} &  specify the flags to link with the library
286XXX package \\
287&where XXX is one of LP solver packages: cplex, glpk, osl, soplex, \\
288& xpress \\
289\texttt{--with-lp-solver[=lpsolver]} &  specify the LP solver in small
290letters (default lpsolver=clp) \\
291\texttt{ --with-gmpl} &  compile with GMPL reader (requires
292\texttt{--with-glpk-incdir} and \\ &
293\texttt{--with-glpk-lib} options to be set) \\
294\texttt{--with-osi-interface} &  compile with SymOsi interface \\
295\texttt{--with-application} &  compile the application library \\
296\hline
297\texttt{--enable-openmp} &   compile in OpenMP features \\
298\texttt{--with-pvm } &  compile in parallel architecture (assuming that pvm is \\
299&installed and the variable PVM\_ROOT is defined.) \\
300\texttt{--without-cg} &  compile without cut generator module \\
301\texttt{--without-cp} &  compile without cut pool module \\
302\texttt{--without-lp} &  compile without LP solver module \\
303\texttt{--without-tm} &  compile without tree manager module
304\end{tabular}
305\caption{A list of useful configuration options \label{conf_opts}}
306\end{figure}
307
308In order to enable or disable an option, either modify the file
309\code{share/config.site} or add the option as an argument to configuration
310script. For instance, running
311{\color{Brown}
312\begin{verbatim}
313 ./configure --enable-debug
314\end{verbatim}
315}
316will compile the source files with the debugging flag.
317
318It is possible to use compilers oter than the default (which is \code{g++}).
319For example, to perform at automated build of SYMPHONY using the MSVC++
320compiler \code{cl} with GNU autotools in the CYGWIN environment configure with
321{\color{Brown}
322\begin{verbatim}
323 ./configure CC=cl CXX=cl
324\end{verbatim}
325}
326
327\subsubsection{Building}\label{building}
328
329After configuring, the code can be built by typing the commands
330{\color{Brown}
331\begin{verbatim}
332 make
333 make install
334\end{verbatim}
335} This will first create the required libraries and executables and then will
336install them. By default, the library {\color{Brown}\texttt{libSym}} and the
337executable {\color{Brown}\texttt{symphony}} will be installed to the
338{\color{Brown}\texttt{lib/}} and {\color{Brown}\texttt{bin/}} directories. To
339install in another directory, use the option
340{\color{Brown}\texttt{--prefix=DIR}} to the {\color{Brown}\texttt{configure}}
341command.
342
343After compilation, the SYMPHONY library, together with the header files in the
344subdirectory {\color{Brown}\texttt{include/}}, can then be used to call
345SYMPHONY from any C/C++ code. The API for this is described in
346Chapter~\ref{API-overview}. The executable can also be used for solving
347generic MILP problems in MPS and GMPL format. In order to read GMPL files, you
348will need to have GLPK (\url{http://www.gnu.org/software/glpk/}) installed and
349SYMPHONY must be configured with {\color{Brown}
350\begin{verbatim}
351 ./configure --with-gmpl --with-glpk-lib[=GLPK library location]
352             --with-glpk-incdir[=GLPK include dir]
353\end{verbatim}
354}
355For a more powerful modeling interface, FlopC++ can also be used to obtain a
356capability similar to ILOG's Concert technology for building math programming
357models (see SYMPHONY/Examples/FLOPC++).
358
359To test SYMPHONY after building, type
360{\color{Brown}
361\begin{verbatim}
362 make test
363\end{verbatim}
364} to execute an automated unit test. To test out the optimizer manually. a
365sample MPS file called \code{sample.mps} and a sample GMPL/AMPL file called
366{\color{Brown}\texttt{sample.mod}} together with its data file
367{\color{Brown}\texttt{sample.dat}} are included with the distribution. You can
368use either the command-line or the interactive optimizer. To solve the sample
369MPS model, type {\color{Brown}
370\begin{verbatim}
371 bin/symphony -F SYMPHONY/Datasets/sample.mps
372\end{verbatim}
373} To solve the GMPL model, use the \code{-F} switch to specify the file name
374and the \code{-D} for the data file name if the input is in GMPL/AMPL format,
375i.e., type
376{\color{Brown}
377\begin{verbatim}
378 bin/symphony -F SYMPHONY/Datasets/sample.mod -D SYMPHONY/Datasets/sample.dat
379\end{verbatim}}
380For more MPS data files for further testing, see the MIPLIB library in the
381\code{Data/} subdirectory. To run the interactive optimizer, execute SYMPHONY
382without any command-line arguments, i.e., type
383{\color{Brown}
384\begin{verbatim}
385  bin/symphony
386\end{verbatim}}
387and then type \code{help} or \code{?} to see a list of available commands.
388After the SYMPHONY library and the executable are compiled and tested, you
389can type
390{\color{Brown}
391\begin{verbatim}
392 make clean
393\end{verbatim}}
394if you want to save disk space. That's it! Now you are ready to use SYMPHONY
395callable library or solve generic MILP problems through the executable.
396
397\subsubsection{Building for parallel architectures}
398
399\paragraph{Shared-memory architectures.}
400
401To compile a shared memory version of SYMPHONY, simply use an OpenMP compliant
402compiler. Version \VER\  has been tested with gcc 4.2, and should build by
403configuring with
404{\color{Brown}
405\begin{verbatim}
406 ./configure --enable-openmp
407\end{verbatim}
408}
409After configuring, follow the earlier instructions for building and testing.
410To invoke SYMPHONY from the command-line with multiple threads, specify the
411number of threads with the \code{-p} option, i.e., {\color{Brown}
412\begin{verbatim}
413 bin/symphony -p 2 -F SYMPHONY/Datasets/sample.mps
414\end{verbatim}
415}
416
417\paragraph{Distributed-memory architectures}
418\label{distributed-build}
419
420%\paragraph{Installing PVM.}
421\label{PVM}
422To compile a distributed application, it is necessary that PVM be installed
423either in the system path or in the directory pointed to by the environment
424variable \code{PVM\_ROOT} (this can be your home directory if PVM is not
426version can be obtained at \texttt{
428{http://www.csm.ornl.gov/pvm/}}. It should compile and install without
429problems on most architectures. You will have to make a few modifications to
430your \code{.cshrc} file, such as defining the \code{PVM\_ROOT} environment
431variable, but this is all explained clearly in the PVM documentation. Note
432that all executables (or at least a link to them) must reside in the
433\code{\$PVM\_ROOT/bin/\$PVM\_ARCH} directory in order for parallel processes
434to be spawned correctly. The environment variable \code{PVM\_ARCH} is set in
435your \code{.cshrc} file and should contain a string representing the current
436architecture type. To run a parallel application, you must first start up the
437daemon on each of the machines you plan to use in the computation. How to do
438this is also explained in the PVM documentation.
439
440%\paragraph{Configuring.}
441
442To configure for a parallel build with the default parallel configuration,
443invoke the configuration script as follows: {\color{Brown}
444\begin{verbatim}
445 ./configure --with-pvm
446\end{verbatim}
447}
448Note that there are a number of different parallel configurations (see
449Chapter \ref{SYMPHONY-modules} for an overview of SYMPHONY's parallel
450modules). The default configuration is to build two parallel modules, the
451first consisting of the master, tree management, and cut management modules,
452while the second consisting of the node processing, and cut generation
453modules. To build in another configuration, there are four configure flags
454that control which modules run as separate executables and which are called
455directly in serial fashion. The variables are as follows:
456\begin{description}
457        \item[] \code{--with-cg}: If set, then the cut generator function will
458        be called directly from the LP in serial fashion, instead of running
459        as a separate executable. This is desirable if cut generation is quick
460        and running it in parallel is not worth the price of the communication
462        \item[] \code{--with-cp}: If set, then the cut pool(s) will be
463        maintained as a data structure auxiliary to the tree manager.
464        \item[] \code{--with-lp}: If set, then the LP functions will be called
465        directly from the tree manager. When running the distributed version,
466        this necessarily implies that there will only be one active subproblem
467        at a time, and hence the code will essentially be running serially. In
468        the shared-memory version, however, the tree manager will be threaded
469        in order to execute subproblems in parallel.
470        \item[] \code{--with-tm}: If set, then the tree will be managed
471        directly from the master process. This is only recommended if a single
472        executable is desired (i.e.~the three other variables are also set to
473        true). A single executable is extremely useful for debugging purposes.
474\end{description}
475These variables can be set in virtually any combination, though some
476don't really make much sense. Note that in a few user functions that
477involve process communication, there will be different versions for
478serial and parallel computation. This is accomplished through the use
479of \code{\#ifdef} statements in the source code. This is well documented
480in the function descriptions and the in the source files containing
481the function stubs.
482
483%\paragraph{Building.}
484
485Once configured, follow the build instructions in Section \ref{building-unix}
486to build the code. Note that this will also compile the sequential version.
487Make sure there are links from your \code{\$PVM\_ROOT/bin/\$PVM\_ARCH}
488subdirectory to each of the executables in your \code{bin/} directory, as
489required by PVM. In order to keep track of the various possible
490configurations, executable and their corresponding libraries are named as
491follows. The name of each executable is \code{symphony}, along with a
492combination of the (abbreviated) names of the modules that were combined to
493produce that executable joined by underscores: \code{m} for the master module,
494\code{tm} for the tree management module, \code{lp} for the node processing
495module, \code{cg} for the cut generation module, and \code{cp} for the cut
496management module. For instance, in the default distributed configuration, the
497executables produced are \code{symphony\_m\_tm\_cp} and
498\code{symphony\_lp\_cg}.
499
500To test the parallel version, first start the PVM daemon by typing \code{pvm}
501on the command line and then typing \code{quit}. As above, invoke SYMPHONY
502using the sample MPS file called \code{sample.mps} included with the
503distribution. To specify the file name, use the \code{-F} command-line option,
504i.e., in the root directory, type {\color{Brown}
505\begin{verbatim}
506 bin/symphony_m_EXT -F SYMPHONY/Datasets/sample.mps
507\end{verbatim}
508}
509
510where \code{EXT} is the extension to be added according to the chosen
511configuration of the modules.
512
513\subsubsection{Building SYMPHONY Applications}
514\label{build_appl_unix}
515
516There are a number of sample applications available as examples of how to do
517customized development with SYMPHONY. These include customized solvers for the
518matching problem, the set partitioning problem (simple and advanced versions),
519the vehicle routing and traveling salesman problems, the mixed postman
520problem, the multi-criteria knapsack problem, and the capacitated network
521routing problem. These applications are contained in the
522\code{SYMPHONY/Applications/} subdirectory in the distribution. There is also
523a white paper that guides the user through the development of the MATCH solver
524in the \code{SYMPHONY/Doc/} directory. For detailed instructions on developing
525your own application with SYMPHONY, see Chapter \ref{SYMPHONY-development}.
526
527In order to compile SYMPHONY's applications in Unix-like environments, you
528must first compile a version of the callable library with hooks for the
529callback functions. {\color{Brown}
530\begin{verbatim}
531 ./configure --with-application
532 make
533 make install
534\end{verbatim}
535} This will create the application library called \code{libSymAppl} to be used
536while building custom applications. Note that that the generic sequential
537library and executable will also be made and installed.
538
539After building the library, go to one of the application subdirectories in the
540\code{SYMPHONY/Applications/} directory and type \code{make} there to build
542configuration instructions, see the INSTALL file of the corresponding
543application.
544
545\subsection{Building Using Microsoft Visual C++}
546\label{getting_started_windows}
547
548Here is a sketch outline of how to compile SYMPHONY in MS Windows with the
549MSVC++ compiler. These instructions will lead you through the steps required
550to compile SYMPHONY as a generic MILP solver. Note that the Windows version
551has some limitations. Detailed timing information is not currently provided.
552Support is only provided for running in sequential mode at this time.
553
556create the directory \code{SYMPHONY-\VER}. You now have three options. You
557can either build using the MSVC++ IDE, build on the command-line with MSVC++
558compiler, or use the NMAKE utility.
559
560\subsubsection{Building with the MSVC++ Graphical Interface}
561\label{using_msvc}
562
563These instructions are for MSVC++ Version 8. Instructions for other versions
564should be similar.
565
566\begin{itemize}
567
568\item Go to \code{Win32\bs v8} directory and open the solution file
569\code{symphony.sln}.
570
571\item Note that there are a number of additional preprocessor definitions that
572control the functionality of SYMPHONY. These definitions are described in
573\code{sym.mak}, a Unix-style makefile included in the distribution. To
574enable the functionality associated with a particular definition, simply add
575it to the list of definitions of \code{libSymphony} project together with
576the required libraries and paths. For instance, if you
577want to enable GMPL reader option, you need to
578\begin{itemize}
579  \item add the directory of the header files of GLPK to the include
580files path
581  \item add \code{USE\_GLPMPL} to the defines
582  \item add the GLPK library to the workspace
583\end{itemize}
584\item Make sure that the project \code{symphony} is set as the startup project
585by choosing \code{Set as Startup Project} from the \code{Project} menu after
586selecting the \code{symphony} project in the Solution Explorer. Choose
587\code{Build Solution} from the Build menu. This should successfully build
588the SYMPHONY library and the corresponding executable.
589
590\item To test the executable, go to the \code{Debug} tab and choose
592interactive solver will appear. Type \code{help} or \code{?} to see a list of
593available commands or see Chapter \ref{API-overview} for instructions on using
594the interactive solver.
595
596\end{itemize}
597
598Note that there is some functionality missing from the Windows version. Most
599prominently, the timing functions do not work. In addition, the Windows
600version will only run in sequential mode for a variety of reasons. However, it
601should be relatively easy to get it running in parallel if you can get PVM
602working under Windows.
603
604\subsubsection{Building in a Windows Terminal}
605\label{using_msdev}
606
607These instructions are for MSVC++ Version 8. Instructions for other versions
608should be similar.
609
610\begin{itemize}
611\item Open a command terminal (choose \code{Run} on the Start menu and type
612\code{cmd} in the dialogue box). Go to the \code{Win32\bs v8}
613directory and type
614{\color{Brown}
615\begin{verbatim}
616 devenv symphony.sln /build all
617\end{verbatim}
618}
619This will create both the debug and release versions of SYMPHONY. If you
620want to compile only one of them, type
621{\color{Brown}
622\begin{verbatim}
623 devenv symphony.sln /build "all - debug"
624\end{verbatim}
625}
626or
627{\color{Brown}
628\begin{verbatim}
629 devenv symphony.sln /build "all - release"
630\end{verbatim}
631}
632For each command, the library \code{libSymphony.lib} and the executable
633\code{symphony} will be created in \code{Debug} and/or \code{Release}
634directories.  The library, together with the header files in
635\code{SYMPHONY\bs include\bs}, can then be
636used to call SYMPHONY from any C/C++ code. The API for calling SYMPHONY is
637described in Section \ref{callable_library}.
638
639\item Test the executable by opening Windows Explorer and double-clicking
640on {\color{Brown}\texttt{symphony.exe}} in the
641{\color{Brown}\texttt{Debug\bs}} subdirectory. This should open a Window in
642which the interactive solver will appear. Type \code{help} or \code{?} to see
643a list of available commands or see Chapter
644\ref{API-overview} for instructions on using the interactive solver.
645
646\item If you modify the source code of SYMPHONY, type
647{\color{Brown}
648\begin{verbatim}
649 devenv symphony.dsw /make all /rebuild
650\end{verbatim}
651}
652in order to clean and rebuild everything.
653\end{itemize}
654
655\subsubsection{Building with the MSVC++ compiler in CYGWIN}
656
657It is possible to perform at automated build of SYMPHONY using the MSVC++
658compiler \code{cl} with GNU autotools in the CYGWIN environment. To do so,
659follow the instuctions for building in Unix-like environments (see Section
660\ref{getting_started_unix}), except when configuring, use the command
661
662{\color{Brown}
663\begin{verbatim}
664 ./configure CC=cl CXX=cl
665\end{verbatim}}
666
667\subsubsection{Building with the NMAKE Utility}
668\label{using_nmake}
669
670\begin{itemize}
671\item Go to \code{Win32} directory and edit the \code{sym.mak}
672makefile to reflect
673your environment. This involves specifying the LP solver to be used,
674assigning some variables and  setting various paths. Only minor edits
675should be required. An explanation of what has to be set is contained in the
676comments in the makefile.  Note that, you have to first create the COIN
677libraries \ptt{Cgl}, \ptt{Clp}, \ptt{Osi}, \ptt{OsiClp} and \ptt{CoinUtils}
678which reside in \code{Win32/v6} directory.
679
680\item Once configuration is done, open a command line terminal and type
681{\color{Brown}
682\begin{verbatim}
683 nmake sym.mak
684\end{verbatim}
685}
686This will make the SYMPHONY library \code{libSymphony.lib} and the executable
687\code{symphony} in \code{Debug} directory. The library, together with the
688header files in \code{SYMPHONY\bs include\bs}, can then be used to call
689SYMPHONY from any C/C++ code. The API for calling SYMPHONY is described in
690Section \ref{callable_library}.
691
692\item Test the executable by opening Windows Explorer and double-clicking
693on {\color{Brown}\texttt{symphony.exe}} in the
694{\color{Brown}\texttt{Debug\bs}} subdirectory. This should open a Window in
695which the interactive solver will appear. Type \code{help} or \code{?} to see
696a list of available commands or see Chapter \ref{API-overview} for
697instructions on using the interactive solver.
698
699\end{itemize}
700
701\subsection{Building SYMPHONY Applications}
702\label{build_appl_msvc}
703
704As mentioned above, there are a number of sample applications available as
705examples of how to do development with SYMPHONY. These include solvers for the
706matching problem, the set partitioning problem (simple and advanced versions),
707the vehicle routing and traveling salesman problems, the mixed postman
708problem, multi-criteria knapsack problem and, capacitated network routing
709problem. These applications are contained in the \code{SYMPHONY/Applications/}
710subdirectory in the distribution. There is also a white paper that guides the
711user through the development of the MATCH solver in the \code{SYMPHONY/Doc/}
712directory. For instructions on developing your own application with SYMPHONY,
713see Chapter \ref{SYMPHONY-development}.
714
715In order to compile SYMPHONY's applications in the Microsoft Visual C++
716environment, obtain the source code as described earlier. As before, you then
717have three options. You can either build using the MSVC++ IDE, build on the
718command-line with MSVC++ executable, or use the NMAKE utility. The below
719instructions are for MSVC++ Version 6, but building in other versions should
720be similar. All of the following commands should be executed in the
721\code{SYMPHONY-\VER\bs Applications\bs XXX\bs Win32\bs v6} directory, where
722\code{XXX} is the name of the application to be built.
723
724\subsubsection{Building With the MSVC++ IDE}
725
726\begin{itemize}
727
728\item Open the workspace \code{xxx.dsw}.
729
730\item The configuration steps are exactly the same as that described in
731  Section \ref{using_msvc}. The only difference is that you are using the
732  \code{xxx} project instead of the \code{symphony} project. Go through the
733  same steps to configure.
734
735\item Once you have the proper settings, choose \code{Build
736xxx.exe} from the \code{Build} menu. This should successfully
737build the executable.
738
739\item
740To test the executable, right click on the \code{xxx} project, go to the
741\code{Debug\bs} tab and set the program arguments to
742\code{-F ..\bs ..\bs sample.xxx}. Note that command-line switches are
743Unix-style.
744
745\item
746Now choose \code{Execute} from the build menu and you have a working branch
747and bound solver.
748
749\end{itemize}
750
751\subsubsection{Building in a Windows Terminal}
752\begin{itemize}
753\item Open a command terminal (choose \code{Run} on the Start menu and type
754\code{cmd} in the dialogue box) and type
755{\color{Brown}
756\begin{verbatim}
757 devenv xxx.sln /make all
758\end{verbatim}
759} where \code{xxx} is the name of the application. This will create both the
760debug and release versions of the application executable. If you want to
761compile only one of them, type
762{\color{Brown}
763\begin{verbatim}
764 devenv xxx.sln /make "all - debug"
765\end{verbatim}
766}
767or
768{\color{Brown}
769\begin{verbatim}
770 devenv xxx.sln /make "all - release"
771\end{verbatim}
772}
773For each command, the executable \code{user} will be created in
774\code{Debug\bs} and/or \code{Release\bs}
775directories.
776
777\item To test the executable, type
778{\color{Brown}
779\begin{verbatim}
780 Debug\xxx.exe -F ..\..\sample.xxx
781\end{verbatim}
782}
783\item If the source files for the application are modified, type
784{\color{Brown}
785\begin{verbatim}
786 devenv user.sln /make all /rebuild
787\end{verbatim}
788}
789in order to clean and rebuild everything.
790\end{itemize}
791
792\subsubsection{Using the NMAKE Utility}
793
794\begin{itemize}
795\item
796Edit the file \code{xxx.mak}, where \code{xxx} is the name of the application,
797to reflect your environment. Only minor edits should be required. An
798explanation of what has to be set is contained in the comments in the
799\code{xxx.mak} file. Also, see the related parts of Section \ref{using_nmake}
800above.
801
802\item Once configuration is done, type
803{\color{Brown}
804\begin{verbatim}
805  nmake /f xxx.mak
806\end{verbatim}
807}
808The executable \code{xxx.exe} will be created in the \code{Debug/} directory.
809\item To test the executable, type
810{\color{Brown}
811\begin{verbatim}
812 Debug\xxx.exe -F ..\..\sample.xxx
813\end{verbatim}
814}
815\end{itemize}
816
Note: See TracBrowser for help on using the repository browser.