source: trunk/documents/UserDoc/DocBookUsersGuides/InstallationGuide/xml/PCMachines/pcMachines.xml @ 1358

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.Cygwin">
<title>
Windows with the Cygwin Toolset and Microsoft Visual C++
</title>

<para>
To compile and run Geant4 under Windows systems, some additional
information and tools are required, although the installation
produre is similar to that required on a UNIX based system. On
Windows, the Cygwin toolset and the Microsoft Visual C++ compiler
are used.
</para>

<para>
Cygwin32 is a UNIX development environment available for Microsoft
Windows. You can freely obtain Cygwin32 from 
<ulink url="http://cygwin.com/">
Cygwin
</ulink>
or 
<ulink url="http://x.cygwin.com/">
Cygwin/X
</ulink>
.
</para>

<para>
We do not support direct use of Visual Studio; i.e. we do not
provide Visual Studio workspace (.dsw) or project (.dsp) files, nor
we do provide makefiles for the <literal>nmake</literal> application of MS
Visual C++.
</para>

<para>
We use several of the tools provided by the Cygwin toolset:

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>make.exe</literal> as a make tool
  </para></listitem>
  <listitem><para>
    <literal>g++.exe</literal> as a tool to analyse source file dependencies
    and create dependency (<literal>.d</literal>) files
  </para></listitem>
  <listitem><para>
    several other unix tools like <literal>cp</literal>, <literal>mv</literal>,
    <literal>rm</literal>, <literal>touch</literal>, etc.
  </para></listitem>
</itemizedlist>
</para>

<para>
At the installation of the Cygwin toolset it is therefore required
to explicitely select some packages (i.e. <emphasis>gmake</emphasis>, 
<emphasis>gcc</emphasis>, <emphasis>binutils</emphasis> 
and <emphasis>tcsh</emphasis> from the "devel" category) in
addition to those which are part of the default installation.
</para>

<para>
For more details on the toolset, please see the documentation
available on the 
<ulink url="http://cygwin.com/">
Cygwin pages
</ulink>
. 
The User's Guide has quick start guides and help with
setting up Cygwin with <literal>setup.exe</literal>.
</para>

<para>
Links to some installation tips for the Cygwin toolset and also 
"step by step" installation guides can be found in the section
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas06.html">
Appendix - Step-by-Step Installation Guides - Build for MS Visual C++
</ulink> 
of <emphasis>Geant4 User's Guide - For Application Developers</emphasis>.
</para>

<para>
The usage of Cygwin32 for the build environment results in a
build procedure similar to that on a UNIX system.
</para>

<para>
The following steps are required to install geant4:

<orderedlist spacing="compact">
  <listitem><para>
    Install Cygwin (see also notes above and additional
    <ulink url="http://cern.ch/geant4/support/windows_note.shtml">installation
    notes</ulink> for known issues related to the most current version):
    <para>
    We do not depend on any specific feature of the version of Cygwin,
    so newer versions (or slightly older) are expected to work.
    </para>
  </para></listitem>
  <listitem><para>
    Set the environment for MS Visual C++, i.e. set the paths to
    libraries, include files, and executables for MS Visual C++. This
    can be done by modifying the start-up batch file
    <literal>cygwin.bat</literal> of Cygwin32 to include all the MSDOS commands
    found in the file <literal>vcvars32.bat</literal> provided in MS Visual C++
   (in the VC++ .NET compiler installation directory, and usually
   located inside the <literal>Common7/Tools</literal> directory). This
   modification should be done after the installation of the Cygwin
   toolset, so that the environment gets properly set at the time of
   the invocation of the shell.
  </para></listitem>
  <listitem><para>
    Unpack the source code into a directory of your choice.
  </para></listitem>
  <listitem><para>
    Start the <literal>Cygwin</literal> shell from the start menu.
  </para></listitem>
  <listitem><para>
    At this point you're ready to install Geant4. If manual
    installation is chosen, you must set the necessary environment
    variables. There are various ways to do so; for example through a
    command file for the Cygwin bash shell. This command file could be
    named <literal>geant4-setup.sh</literal>, and you must execute it with

    <informalexample>
    <programlisting>
        . geant4-setup.sh
    </programlisting>
    </informalexample>

    including the leading dot and blank space. You could also have this
    as your <literal>.bashrc</literal> file. The commands in the command file
    should be:

    <informalexample>
    <programlisting>
        # Set G4SYSTEM 
        export G4SYSTEM=WIN32-VC
        #
        # Set Path to CLHEP
        export CLHEP_BASE_DIR=C:/usr/local
        #
        # --- Other optional settings
        #Turn on verbose to show command used for compilation
        #export CPPVERBOSE=1
        #
    </programlisting>
    </informalexample>
    Note, in the example above, CLHEP was installed in
    <literal>C:/usr/local</literal>, therefore <literal>include/CLHEP</literal> and
    <literal>lib/CLHEP.lib</literal> must be included therein.
  </para></listitem>
  <listitem><para>
    Once the environment is correctly set, the libraries are built
    using make from the <literal>geant4/source</literal> directory typing
    <literal>make</literal> from the <literal>Cygwin bash</literal> shell
    prompt.
  </para></listitem>
</orderedlist>
</para>

<para>
Examples can be built in the same way as the libraries from
examples/novice/N01, for instance: type <literal>make</literal> from the
shell prompt.
</para>

<para>
Note that, depending on which external software is used, there may
be some warnings in linking about conflictings libraries. This often
seems to be caused by an external library compiled for a different
run time environment.
</para>

<para>
The binary of the example is placed by default into the
<literal>geant4/bin/WIN32-VC</literal> directory. You may run it either from
this directory or from the <literal>examples/novice/N01</literal> directory;
sample input and output files are placed in each of the
<literal>examples/novice</literal> directories. Some of the examples will
need to read data files, and the place has to be given in
environment variables again similar to the following example:

<informalexample>
<programlisting>
        #
        # Environment variables needed to find geant4 data files:
        #
        # Data for neutron scattering processes, 
        #    distributed in a separate tar file, then placed under data
        export G4NEUTRONHPDATA=c:/usr/local/geant4/data/G4NDL
        #
        # Nuclear Photon evaporation data,
        #    distributed with the source files under data 
        export G4LEVELGAMMADATA=c:/usr/local/geant4/data/PhotonEvaporation
        #
        # Data for radiative decay hadronic processes under data,
        #    distributed in a separate tar file
        export G4RADIOACTIVEDATA=c:/usr/local/geant4/data/RadiativeDecay
        #
        # Data for low energy electromagnetic processes,
        #    distributed in a separate tar file, then placed under data
        export G4LEDATA=c:/usr/local/geant4/data/G4EMLOW
        #
        # Data for nuclear shell effects for INCL/ABLA hadronic model,
        #    distributed in a separate tar file, then placed under data
        export G4ABLADATA=c:/usr/local/geant4/data/G4ABLA
        #
        # Data for measured optical surface reflectance in optical processes,
        #    distributed in a separate tar file, then placed under data
        export G4REALSURFACEDATA=c:/usr/local/geant4/data/RealSurface
        #
</programlisting>
</informalexample>
</para>

<para>
All compiler and linker options are set in
<literal>config/sys/WIN32-VC.gmk</literal>. If you require options different
from our choice, you can modify this file. 
</para>

</sect1>


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.BuildLibDLLs">
<title>
Building Kernel Libraries DLLs
</title>

<para>
DLLs (Dynamic Link Libraries) on Windows are supported for MS-VC++
and can be built for the <literal>compound</literal> kernel libraries of
Geant4 (see <xref linkend="sect.InstManually.OptEnvVar"/> of the
Installation Procedure of this Guide for a dissertation on
<literal>global/compound</literal> libraries).
</para>

<para>
The libraries can be built either manually, issuing the
command:

<informalexample>
<programlisting>
        make dll
</programlisting>
</informalexample>

from the directory <literal>$G4INSTALL/source</literal> or by specifying it
through the <literal>Configure</literal> script used for the
installation.
</para>

<para>
Then, to build any application making use of the installed DLLs,
the environment variable <literal>G4LIB_USE_DLL</literal> must be set in the
environment.
</para>

<para>
Once the application is built, it is required to specify to the
system the path where the DLLs are installed. To do so, add the
absolute path (in Cygwin format) of the DLLs installation directory
to the <literal>PATH</literal> variable; for example:

<informalexample>
<programlisting>
        export PATH=$PATH:/usr/local/geant4/lib/$G4SYSTEM
</programlisting>
</informalexample>
</para>

<para>
You may then be able to run successfully your application.
</para>


</sect1>