geant4/examples/README.HowToRun.md

0001 \page README_HowToRun How to build and run an example
0002
0003 All basic and most of extended examples have a similar structure.
0004 The `main()` function is included in `exampleXYZ.cc` in the example top directory
0005 and the example source code is structered in `include` and `src` subdirectories.
0006 When the example is built, the executable takes the same name as the file with
0007 `main()` function without the `.cc` extension, `exampleXYZ`.
0008
0009 Then several macros are provided to run the example with various start-up
0010 conditions. These macros have usually the `.mac` extension. Besides these macros,
0011 there is often a macro `exampleXYZ.in` (note its different extension)
0012 which is used in Geant4 testing and which output, `exampleXYZ.out`, can be also included
0013 in the distribution.
0014
0015 You can find all details about building the examples in the <a href= "https://geant4-userdoc.web.cern.ch/UsersGuides/InstallationGuide/html/index.html"> Geant4 Installation Guide </a>, in the section <a href="https://geant4-userdoc.web.cern.ch/UsersGuides/InstallationGuide/html/buildtools.html">  How to Use the Geant4 Toolkit Libraries </a>.
0016 Here we recall only the basics.
0017
0018 ## Compile and link to generate an executable
0019
0020 ```
0021 % cd path_to_exampleXYZ     # go to directory which contains your example
0022 % mkdir exampleXYZ_build
0023 % cd exampleXYZ_build
0024 % cmake -DGeant4_DIR=path_to_Geant4_installation/lib[64]/cmake/Geant4/ ../exampleXYZ
0025 % make -j N exampleXYZ      # "N" is the number of processes
0026 ```
0027
0028 ## Execute exampleXYZ in 'batch' mode from macro files
0029
0030 ```
0031 % cd exampleXYZ_build
0032 % ./exampleXYZ  xyz.mac
0033 ```
0034
0035 ## Execute exampleXYZ in the 'interactive mode' with visualization
0036 ```
0037 % cd exampleXYZ_build
0038 % ./exampleXYZ
0039 ....
0040 Idle> type your commands
0041 ....
0042 Idle> exit
0043 ```
0044
0045 See also the explicit instructions for building TestEm1 example at
0046 \ref README_HowToRunTestEm1 page.
0047
0048 \page README_HowToRunTestEm1 How to build and run TestEm1 example
0049
0050 Below we give the explicit instructions (described in general at \ref README_HowToRun page) for the example extended/electromagnetic/TestEm1.
0051
0052 Let's suppose that the `TestEm1` directory is available in `$HOME` and Geant4 installation in `/usr/local` and we work within the `bash` shell on a `64-bit machine.
0053
0054 ## Compile and link TestEm1 to generate an executable
0055
0056 ```
0057 % cd $HOME
0058 % mkdir TestEm1_build
0059 % cd TestEm1_build
0060 % cmake -DGeant4_DIR=/usr/local/lib64/Geant4-11.3.0/ ../TestEm1
0061 % make -j 2 TestEm1
0062 ```
0063
0064 ## Execute TestEm1 in 'batch' mode from macro files
0065 ```
0066 % cd $HOME/TestEm1_build
0067 % ./TestEm1 annihil.mac
0068 % ./TestEm1 brem.mac
0069 % ./TestEm1 TestEm1.in >& myTestEm1.out   # redirecting output in a file
0070 ```
0071
0072 ## Execute TestEm1 in 'interactive mode' with visualization
0073 ```
0074 % cd $HOME/TestEm1_build
0075 % ./TestEm1
0076 PreInit> /run/initialize
0077 Idle>    /run/beamOn 1
0078 ...
0079 Idle>    exit
0080 ```