G4beamline BUILD.txt G4beamline 2.12 April 2012 TJR The build process for G4beamline has been completely revised to make it much easier for users to build it from source. This makes it straightforward to install it on unsupported systems, and for users to add their own code. Note that it typically takes 4-8 hours to build from source on a single-core system (multiple cores can speed that up considerably). So it's usually best to use the binary distribution if it works for you. NOTE: The build system has changed again, to parallel that of Geant4 9.5, which uses Cmake. G4beamline does not use Cmake itself, but its build system has been greatly streamlined. The basic changes are: * the build directory is now separate from the source directory * the entire build system is contained in a single file, configure * the configure script constructs a Makefile that builds all libraries and G4beamline itself * Each library build is straightforward, using its own configure/make or its own cmake BASIC REQUIREMENTS ------------------ * The source distribution from http://g4beamline.muonsinc.com * The g++ compiler and its libraries * Cmake from http://www.cmake.org * The X-windows system and its DEVELOPMENT libraries * Motif and its DEVELOPMENT library * A system Expat library on Mac and Linux. * Java, for running the GUI. * At least 2 GigaByte-s of free disk space for the source and build directories (the libraries are huge --- over 2 million lines of code) * On Windows, the Cygwin environment is required, as well as the free Microsoft Visual C++ express Edition (compiling with g++ is possible with --disable-visual, but runs considerably slower). Note that when building with VC++, g++ is still needed (for dependencies). RUNNING G4BEAMLINE VIA THE COMMAND LINE --------------------------------------- After a successful build, to run G4beamline you must first: source G4beamline-VERSION/bin/g4bl-setup.sh This will put the bin directory into your PATH, and set the variable G4BL_DIR to the install directory. You may put this command into your $HOME/.bash_profile if you wish. There is also g4bl-setup.csh. Commands: g4bl sets up required environment variables and runs g4beamline g4blgui runs the GUI (requires Java) g4bl-config used internally by other scripts g4blmake for building G4beamline with your code g4blmovie creates a movie g4bl-setup.sh sets up the G4beamline environment for Bourne shells g4bl-setup.csh sets up the G4beamline environment for csh shells g4bldata downloads the physics data sets from CERN g4bl_debug runs the debugger (probably needs to be modified for the specific source files you are interested in) You must also download the Geant4 data sets used by your physics lists. The siomplest way is to run "g4bldata --install", which uses Java to display a GUI interface for the download. Both g4bl and g4blgui will do that if they determine that no data are installed. If you don't have Java, or don't want to use the GUI, run "g4bldata --install-no-gui" (requires wget). After a successful build, you should run the tests (requires Tcl): cd test ./loop The loop command creates a subdirectory, copies the tests there, and runs an infinite loop of all tests (until one fails). ^C will stop it and remove the temporary directory. Individual tests can also be run: cd test ./test07 To test the visualization: cd examples g4blgui example1.in Then select the "best" viewer and push the Run button. The Open Inventor viewer should appear. Note that on Mac OS X 10.4.x (Tiger) and earlier you must issue these commands from an Xterm windows (run the X11 application to get an Xterm window). BUILDING - GENERAL ------------------ After un-tar-ing the source distribution, the basic way to build G4beamline is: # the source has been un-tar-ed in ./G4beamline-VERSION-source mkdir G4beamline-VERSION cd G4beamline-VERSION ../G4beamline-VERSION-source/configure [options...] make There is no "make install", and the program expects to be run from its build directory via an absolute path - the bin/g4bl-setup.sh script arranges that. The configure script has several options that control features of the program: ../G4beamline-VERSION-source/configure --help gives a description. There is also make distrib which builds a binary distribution for your OS. You can then copy this to other systems running that OS and install G4beamline quickly and easily. On Windows you must then run the Advanced Installer application to construct the distribution .msi file. This build system has been tested on the following systems: Scientific Linux Fermi 4.5 Scientific Linux Fermi 5.3 Mac OS X 10.5.8 (Leopard) * Mac OS X 10.6.8 (Snow Leopard) Mac OS X 10.7.3 (Lion) Windows Xp with Cygwin and MS VC++ * Use --old-versions in configure; this OS is no longeer supported. Note that the source code for the following non-system libraries is included in the source distribution for G4beamline: Coin 3-d visualization SoXt Coin <-> X-Windows interface SoWin Coin <-> MS Windows interface CLHEP Class Library for High Energy Physics Geant4 General particle tracking and physics Root Data analysis (used only for NTuple I/O) GSL Gnu Scientific Library FFTW Fastest FFT in the West This is what makes the source distribution so large, but is also what makes it straightforward for users to build the program from source (in release 1.X that typically took a rather frustrating week or more). Note that if you already have any of these installed, they will be ignored and G4beamline will still build its own (private) version within the G4beamline build directory structure. On Windows, some libraries do not play well with this build system, so binary versions are used (they are included in the source distribution). BUILD -- MAC OS X ----------------- This applies to Intel Macs running Leopard, Snow Leopard, and Lion. It should be possible to build and run G4beamline on other versions, but that has not been tested. Tiger (OS X 10.4.X) -- NOT TESTED: *** This OS is no longer supported by either Apple or Geant4 *** These instructions might work; they have not been tested. *** It is strongly suggested you upgrate your OS. * install the X11 application; it's on your install DVD * install the Xcode application version 2.4 or later from your install DVD. Note that versions 3.0 and above won't install on Tiger. * install these packages from the Packages directory of the install DVD: OpenGLSDK.pkg X11SDK.pkg * You must also obtain lesstif; here's what I did: - install fink and Fink Commander from http://www.finkproject.org/ - cd /usr; sudo ln -s X11 X11R6 # Apple uses X11, Fink uses X11R6 BEWARE: the need for this link is very poorly documented, and the Fink error message is useless ("missing dependency x11"). - install via Fink Commander (binary): lesstif lesstif-bin lesstif-shlibs The configure script expects to find Motif in /sw (i.e. include files in /sw/include/Xm and library /sw/lib/libXm.dylib). * remove LibraryBinaries/Darwin-g++/libXm.3.dylib and replace it with /sw/lib/libXm.2.dylib * use --disable-mpi to the configure script * this prescription has not been tested since G4beamline 2.08. Leopard (OS X 10.5.X) *** This OS is no longer supported by either Apple or Geant4 *** These instructions might work; they have not been tested. *** It is strongly suggested you upgrate your OS. Use the instructions for Snow Leopard, but using XCode 3.1.3 and a 32-bit Fink. Install these packages from the Packages directory of the Xcode .dmg or DVD: X11SDK.pkg OpenGLSDK.pkg. This is known to work, but the OpenInventor viewer is crippled: its menus generate many error messages, and don't work. Snow Leopard, and Lion (OS X 10.6.X, 10.7.X): * install the Xcode application. On Snow Leopard, use XCode 3.2.6 from http://developer.apple.com; on Lion, use XCode 4.2 from the App Store. This includes the X11 and OpenGL SDKs. Later versions should work, but these are the versions tested. * You must also obtain Motif (the Open-Source version is called lesstif); here's what I did: - install fink from http://www.finkproject.org/ On Snow Leopard and Lion you want 64-bit Fink. - cd /usr; sudo ln -s X11 X11R6 # Apple uses X11, Fink uses X11R6 BEWARE: the need for this link is very poorly documented, and the Fink error message is useless ("missing dependency x11"). More recent versions of Fink do this automatically. - sudo fink selfupdate - sudo fink install lesstif lesstif-bin lesstif-shlibs The configure script expects to find Motif in /sw (i.e. include files in /sw/include/Xm and library /sw/lib/libXm.dylib). * Install Cmake from cmake.org (I used the binary version on a .dmg). Be sure to install the command-line programs. With these prerequisites, G4beamline should configure and make just fine. Options to configure: Leopard: --old-versions Snow Leopard: (none) Lion: (none) On Leopard and SnowLeopard you can use --enable-mpi. NOTE: if your Mac has multiple cores, configure will determine how many there are and use them all. You can change this via: --cpus=2 (replace 2 with however many concurrent processes you want). This only builds the command-line programs. The applications are built by make distrib Install them from the .dmg as usual. BUILD -- LINUX -------------- Linux is really a wide collection of individual distributions, and it is not possible to test them all. Any recent Linux distribution should be able to build and run G4beamline, as long as the prerequisites can be met; this involves installing software, so you'll need root privileges. On Scientific Linux 5.3, configured as "Generic Desktop" with "software development" installed, the following packages had to be installed: sudo yum groupinstall 'X Software Development' sudo yum install openmotif-devel.i386 sudo yum install libXi-devel Note that other Linux distributions use different commands to install software, and the required libraries will probably have different names. The system must have the usual g++ software development suite installed, plus X-windows development, openmotif development, and perhaps some extra stuff like libXi. You may need to install this: x11-deprecated-libs -- should be available in your Linux distribution, but the name may be different. Some distributions install this automatically, some don't. It provides libXp.so. NOTE: if your system has multiple cores, the build will be greatly sped up if you use this option to configure: --cpus=2 (replace 2 with however many cores are physically present). On a supercomputer, you probably want the following options to confgure: --disable-visual --mpi=/usr --force-mpi If you have a very old version of Linux (more than ~4 years old), you will probably get compilation errors in the libraries. If so, try starting over with "configure --old-versions". BUILD - WINDOWS --------------- You must install Microsoft Visual C++ express edition. http://www.microsoft.com/Express/VC/ I'm using "Visual C++ 2008 Express Edition". The version from 2005 won't compile a program that will run in Vista. I don't know whether programs compiled with 2008 will run on Windows 7, but they do run on Windows Xp and Vista. You must install and use Cygwin. This requires at least some understanding of UNIX commands. http://www.cygwin.com/ You will need your favorite text editor, the g++ compiler suite, Tcl, and lesstif. You must arrange so link is the Microsoft version, not the Cygwin version. This usually requires re-ordering your PATH, or re-naming /bin/link to something else. Note that both GSL and FFTW do not build well on Windows/Cygwin/VC++ -- they insist on using g++ which does not work with the rest of the build compiled with VC++. So there are binary packages wingsl and winfftw that are "built" by merely copying their files appropriately. The origins of these packages have been lost, but they probably were downloaded as pre-built binaries from the corresponding websites.