Difference between revisions of "Old Installation Guide V8.1"

From Wiki OpenGATE
Jump to: navigation, search
(crash edit of V8.1 install instructions)
 
 
(10 intermediate revisions by 3 users not shown)
Line 4: Line 4:
 
You are encouraged to participate in the dialog and post your suggestion or even implementation on the
 
You are encouraged to participate in the dialog and post your suggestion or even implementation on the
 
Gate-users mailing list, the GATE mailing list for users.
 
Gate-users mailing list, the GATE mailing list for users.
You can subscribe to the Gate-users mailing list, by registering to the [http://www.opengatecollaboration.org GATE web site] or directly using this [http://lists.opengatecollaboration.org/mailman/listinfo/gate-users link]
+
You can subscribe to the Gate-users mailing list, by [http://lists.opengatecollaboration.org/mailman/listinfo/gate-users signing up to the gate-users mailing list].
  
If you have a question, it is very likely that it has been asked, answered, and stored in the [http://lists.opengatecollaboration.org/pipermail/gate-users/ archives].
+
If you have a question, it is possible that it has been asked and answered before, and stored in the [http://lists.opengatecollaboration.org/pipermail/gate-users/ archives].
 
These archives are public and are indexed by the usual search engines. By starting your Google search string with <code>site:lists.opengatecollaboration.org</code> you'll get list of all matches of your search on the gate-users mailing list, e.g. [https://www.google.com/search?q=site%3Alists.opengatecollaboration.org+pencilbeam <code>site:lists.opengatecollaboration.org pencilbeam</code>].
 
These archives are public and are indexed by the usual search engines. By starting your Google search string with <code>site:lists.opengatecollaboration.org</code> you'll get list of all matches of your search on the gate-users mailing list, e.g. [https://www.google.com/search?q=site%3Alists.opengatecollaboration.org+pencilbeam <code>site:lists.opengatecollaboration.org pencilbeam</code>].
  
Line 13: Line 13:
  
 
* Check out the bleeding edge development version
 
* Check out the bleeding edge development version
* Report bugs by creating a new "[https://github.com/OpenGATE/Gate/issues issue]"
+
* Report bugs by creating a new "[https://github.com/OpenGATE/Gate/issues issue]". (If you are not entirely sure that what you are reporting is indeed a bug in Gate, then please first check the [http://lists.opengatecollaboration.org/mailman/listinfo/gate-users gate-users mailing list].)
 
* Contribute to Gate by changing the source code to fix bugs or implement new features:
 
* Contribute to Gate by changing the source code to fix bugs or implement new features:
 
** Get a (free) account on GitHub, if you do not have one already.
 
** Get a (free) account on GitHub, if you do not have one already.
** Start by making a fork of the GATE public repository (click the "Fork" button in the upper right corner on the [https://github.com/OpenGATE/Gate/ Gate main page] on GitHub.
+
** [https://git-scm.com/download/linux Install Git] on the computer where you do your development, if it has not yet been installed already. And make sure to configure git [https://help.github.com/articles/setting-your-username-in-git/ with your name] and [https://help.github.com/articles/setting-your-commit-email-address-in-git/ with your email address].
** Note that we use the <code>develop</code> branch to collect all the bleeding edge developments. In the future we may change this to <cdoe>master</code>, like in most other projects on GitHub.
+
** Start by [https://help.github.com/articles/fork-a-repo/ making a fork] of the GATE public repository (click the "Fork" button in the upper right corner on the [https://github.com/OpenGATE/Gate/ Gate main page] on GitHub.
** Then clone your own fork: <code>git clone https://github.com/<YourAccountName>/Gate.git</code> to get the code on the computer that will use to develop and compile Gate.
+
** Note that we use the <code>develop</code> branch to collect all the bleeding edge developments and the <code>master</code> to track the releases. In the future we may merge these two, and use only <code>master</code>, like it's done in most other projects on GitHub. Releases are defined using "tags".
** Make a new branch, dedicated to the bugfix or new feature that want to implement in Gate. You can either create the branch first on GitHub and then <code>git pull</code> it to your clone, or create it directly in your clone and <code>git push</code> it later. Make sure to branch is based on the <code>develop</code> branch. Note that after creating your branch you also need to check it out.
+
** Then clone your own fork: <code>git clone https://github.com/YOUR_USERNAME/Gate.git</code> to get the code on the computer that you will use to develop and compile Gate.
** With <code>git branch -l</code> you can check which branches are available in your clone and which one is currently checked out.
+
** Make a new branch, dedicated to the bugfix or new feature that want to implement in Gate. You can either create the branch first on GitHub and then <code>git pull</code> it to your clone, or create it directly in your clone and <code>git push</code> it later. Make sure that your branch is based on the <code>develop</code> branch. Note that after creating your branch you also need to check it out.
** Now: implement your bugfix or your new feature and commit your changes to your new branch. It's better to make many small commits than a single big one. Use <code>git push</code> to upload your commits to (your fork on) GitHub. This facilitates developing on multiple machines and also avoids loss of time and effort in the unfortunate event of a hardware failure.
+
** With <code>git branch -l</code> you can check which branches are available in your clone and which one is currently checked out. With <code>git checkout <branchname></code> you can change between branches. Be careful not to do this when you still have uncommitted changes (unless you deliberately want to undo those changes).
 +
** Now: implement your bugfix or your new feature and <code>commit</code> your changes to your new branch. It's usually better to make many small commits than a single big one (though it is of course also desirable that every commit leaves the code in a compilable state). Please provide [https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53 concise but informative commit messages]! Use <code>git push</code> to upload your commits to (your fork on) GitHub. This facilitates developing on multiple machines and also avoids loss of time and effort in the unfortunate event of a hardware failure.
 +
**If you are working for a longer time on your fix or new feature, like a few days, weeks or even months, then it is important to make sure to [https://help.github.com/articles/syncing-a-fork/ keep your fork in sync with the upstream repository].
 
** Once you are convinced that your code is OK, make sure it's all pushed to your fork on GitHub. Then:
 
** Once you are convinced that your code is OK, make sure it's all pushed to your fork on GitHub. Then:
 
**# Create a [https://help.github.com/articles/using-pull-requests/ pull-request] from the branch on your Gate repository to the official Gate repository
 
**# Create a [https://help.github.com/articles/using-pull-requests/ pull-request] from the branch on your Gate repository to the official Gate repository
 
**# Provide an example that tests your new feature
 
**# Provide an example that tests your new feature
 
**# If you implemented a new feature, have the associated documentation ready
 
**# If you implemented a new feature, have the associated documentation ready
**# Inform these three people from the collaboration (S. Jan, D.Sarrut and D.J. Boersma) who will then get in touch with you to integrate your changes in the official repository.
+
**# Inform these three people from the collaboration (Sebastien Jan, David Sarrut and David Boersma) who will then get in touch with you to integrate your changes in the official repository.
**For your next bugfix or new feature you do not need to make a new fork, you can use the existing one. But before doing any new work you should make sure to synchronize the <code>develop</code> branch in your fork with the "upstream" (main) <code>develop</code> branch:
+
**For your next bugfix or new feature you do not need to make a new fork, you can use the existing one. But before doing any new work you should make sure to [https://help.github.com/articles/syncing-a-fork/ synchronize] the <code>develop</code> branch in your fork with the "upstream" (main) <code>develop</code> branch:
 
**# Check your "remote repositories" with <code>git remote -v</code>
 
**# Check your "remote repositories" with <code>git remote -v</code>
**# The "origin" repository should be your own fork on GitHub, <code>https://github.com/<YourAccountName>/Gate</code>.
+
**# The "origin" repository should be your own fork on GitHub, <code>https://github.com/YOUR_USERNAME/Gate</code>.
 
**# The "upstream" repository should be the main Gate one, that is <code>https://github.com/OpenGATE/Gate</code>.
 
**# The "upstream" repository should be the main Gate one, that is <code>https://github.com/OpenGATE/Gate</code>.
 
**# If your clone does not yet have an "upstream", then add it with <code>git remote add upstream https://github.com/OpenGATE/Gate</code>.
 
**# If your clone does not yet have an "upstream", then add it with <code>git remote add upstream https://github.com/OpenGATE/Gate</code>.
Line 53: Line 55:
 
* [https://www.cmake.org CMAKE] tool (3.3 or newer)
 
* [https://www.cmake.org CMAKE] tool (3.3 or newer)
  
The ROOT data analysis package may also be needed for post-processing or for using the GATE online plotter (enabling the visualization of various simulation parameters and results in real time). ROOT is available for many platforms and a variety of precompiled packages can be found on the [http://root.cern.ch/ ROOT homepage].
+
The ROOT data analysis package may also be needed for post-processing or for using the GATE online plotter (enabling the visualization of various simulation parameters and results in real time). ROOT is available for many platforms and a variety of precompiled packages can be found on the [http://root.cern.ch/ ROOT homepage]. If your gcc compiler is version 6 or newer, then you should use a recent ROOT 6 release.
  
The [http://www.opengatecollaboration.org/releasedownload LMF] and [http://www.opengatecollaboration.org/ECAT ecat7] packages are also provided on the [http://www.opengatecollaboration.org GATE] website. They offer the possibility to have different output formats for your simulations.
+
The [http://opengatecollaboration.org/sites/default/files/lmf_v3_0.tar.gz LMF] and [http://www.opengatecollaboration.org/ECAT ecat7] packages are also provided on the [http://www.opengatecollaboration.org GATE] website. They offer the possibility to have different output formats for your simulations. Note that this code is very old and not supported by the Gate collaboration, only provided "as is". With newer compilers you may have to do some minor hacking (for ECAT you may need to add compiler flags to select the C90 standard, for instance).
  
 
== Package Requirements ==
 
== Package Requirements ==
 
Compiling software usually requires certain system libraries and compilation tools.
 
Compiling software usually requires certain system libraries and compilation tools.
 
Furthermore, GATE and Geant4 have various package requirements which have to be met BEFORE installing or compiling.
 
Furthermore, GATE and Geant4 have various package requirements which have to be met BEFORE installing or compiling.
Currently lists have been created for Ubuntu 10.04, Ubuntu 11.x, Fedora 14 and Scientifix Linux 6. Visit the [[Package Requirements]] page for detailed package lists.
+
Currently lists have been created for Ubuntu 14.04 (and newer) and SuSE Leap 42.3. Visit the [[Package Requirements]] page for detailed package lists.
  
 
== Installing with MacPorts on OS X ==
 
== Installing with MacPorts on OS X ==
Line 77: Line 79:
  
 
* Geant4 10.4 (available in http://geant4.web.cern.ch/geant4/support/download.shtml).
 
* Geant4 10.4 (available in http://geant4.web.cern.ch/geant4/support/download.shtml).
Note that the 8.1 release remains backward compatible with [http://cern.ch/geant4-data/releases/geant4.10.03.p03.tar.gz Geant4 10.3 patch 03]
+
*:Note that the 8.1 release remains backward compatible with [http://cern.ch/geant4-data/releases/geant4.10.03.p03.tar.gz Geant4 10.3 patch 03]. The [http://opengatecollaboration.org/GateRTion GateRTion 1.0] release, which is very similar to Gate 8.1, can ''only'' be built with Geant4 10.03.p03.
 
* The CLHEP embedded from Geant4 is available (flag OFF by default). Users can also use the external CLHEP (version 2.3.4.3)
 
* The CLHEP embedded from Geant4 is available (flag OFF by default). Users can also use the external CLHEP (version 2.3.4.3)
 
* gcc 4.8 to 7.3
 
* gcc 4.8 to 7.3

Latest revision as of 13:05, 9 October 2019

General Information about GATE

The GATE mailing list

You are encouraged to participate in the dialog and post your suggestion or even implementation on the Gate-users mailing list, the GATE mailing list for users. You can subscribe to the Gate-users mailing list, by signing up to the gate-users mailing list.

If you have a question, it is possible that it has been asked and answered before, and stored in the archives. These archives are public and are indexed by the usual search engines. By starting your Google search string with site:lists.opengatecollaboration.org you'll get list of all matches of your search on the gate-users mailing list, e.g. site:lists.opengatecollaboration.org pencilbeam.

The GATE project on GitHub

GATE project is now publicly available on GitHub. You can use this to:

  • Check out the bleeding edge development version
  • Report bugs by creating a new "issue". (If you are not entirely sure that what you are reporting is indeed a bug in Gate, then please first check the gate-users mailing list.)
  • Contribute to Gate by changing the source code to fix bugs or implement new features:
    • Get a (free) account on GitHub, if you do not have one already.
    • Install Git on the computer where you do your development, if it has not yet been installed already. And make sure to configure git with your name and with your email address.
    • Start by making a fork of the GATE public repository (click the "Fork" button in the upper right corner on the Gate main page on GitHub.
    • Note that we use the develop branch to collect all the bleeding edge developments and the master to track the releases. In the future we may merge these two, and use only master, like it's done in most other projects on GitHub. Releases are defined using "tags".
    • Then clone your own fork: git clone https://github.com/YOUR_USERNAME/Gate.git to get the code on the computer that you will use to develop and compile Gate.
    • Make a new branch, dedicated to the bugfix or new feature that want to implement in Gate. You can either create the branch first on GitHub and then git pull it to your clone, or create it directly in your clone and git push it later. Make sure that your branch is based on the develop branch. Note that after creating your branch you also need to check it out.
    • With git branch -l you can check which branches are available in your clone and which one is currently checked out. With git checkout <branchname> you can change between branches. Be careful not to do this when you still have uncommitted changes (unless you deliberately want to undo those changes).
    • Now: implement your bugfix or your new feature and commit your changes to your new branch. It's usually better to make many small commits than a single big one (though it is of course also desirable that every commit leaves the code in a compilable state). Please provide concise but informative commit messages! Use git push to upload your commits to (your fork on) GitHub. This facilitates developing on multiple machines and also avoids loss of time and effort in the unfortunate event of a hardware failure.
    • If you are working for a longer time on your fix or new feature, like a few days, weeks or even months, then it is important to make sure to keep your fork in sync with the upstream repository.
    • Once you are convinced that your code is OK, make sure it's all pushed to your fork on GitHub. Then:
      1. Create a pull-request from the branch on your Gate repository to the official Gate repository
      2. Provide an example that tests your new feature
      3. If you implemented a new feature, have the associated documentation ready
      4. Inform these three people from the collaboration (Sebastien Jan, David Sarrut and David Boersma) who will then get in touch with you to integrate your changes in the official repository.
    • For your next bugfix or new feature you do not need to make a new fork, you can use the existing one. But before doing any new work you should make sure to synchronize the develop branch in your fork with the "upstream" (main) develop branch:
      1. Check your "remote repositories" with git remote -v
      2. The "origin" repository should be your own fork on GitHub, https://github.com/YOUR_USERNAME/Gate.
      3. The "upstream" repository should be the main Gate one, that is https://github.com/OpenGATE/Gate.
      4. If your clone does not yet have an "upstream", then add it with git remote add upstream https://github.com/OpenGATE/Gate.
      5. Run git status to make sure that you checked out the develop branch, and git pull to make sure that it is in sync with your fork on GitHub and that there no uncommitted edits.
      6. Then run git fetch upstream, followed by git merge upstream/develop.
      7. Now you are ready to create new branches for new bugfixes and features.
  • For more detailed references, recipes, and tutorials on git: please check the web. When copypasting commands, remember that in Gate the "develop" branch currently plays the role of the "master" branch. Our "master" branch is used to track the releases. You will not find the latest bleeding edge code on it. We may change this policy in the near future, to be more conforming to the predominant conventions.

Installing GATE on Linux

This section describes the installation procedure of GATE. This includes three steps:

  • Install Geant4
  • Install ROOT
  • Install GATE

This section starts with a brief overview of the recommended configurations, followed by a short introduction to the installation of Geant4, and then explains the installation of GATE itself on Linux.

It should be highlighted that features depending on external components (libraries or packages) may only be activated if the corresponding component is installed. It is the user's responsibility to check that these components are installed before activating a feature. Except for Geant4, which is closely related to GATE, the user should refer to the Installation Guide of the external components.

In addition, you should also install any Geant4 helper you wish to use, especially OpenGL if required, before installing Geant4 itself. You can either download the source codes and compile the libraries or download precompiled packages which are available for a number of platform-compiler. If you choose to or have to compile the packages, you will need:

  • a C++ compiler (new enough to compile code with the C++11 standard)
  • the GNU version of make
  • CMAKE tool (3.3 or newer)

The ROOT data analysis package may also be needed for post-processing or for using the GATE online plotter (enabling the visualization of various simulation parameters and results in real time). ROOT is available for many platforms and a variety of precompiled packages can be found on the ROOT homepage. If your gcc compiler is version 6 or newer, then you should use a recent ROOT 6 release.

The LMF and ecat7 packages are also provided on the GATE website. They offer the possibility to have different output formats for your simulations. Note that this code is very old and not supported by the Gate collaboration, only provided "as is". With newer compilers you may have to do some minor hacking (for ECAT you may need to add compiler flags to select the C90 standard, for instance).

Package Requirements

Compiling software usually requires certain system libraries and compilation tools. Furthermore, GATE and Geant4 have various package requirements which have to be met BEFORE installing or compiling. Currently lists have been created for Ubuntu 14.04 (and newer) and SuSE Leap 42.3. Visit the Package Requirements page for detailed package lists.

Installing with MacPorts on OS X

GATE can be installed on Mac OS X by following the previous installation instruction on Linux. An alternative way is to install Gate via MacPorts (http://www.macports.org/) with

   sudo port install gate

Apart from the `Gate` command this also installs a standalone app:

   /Applications/MacPorts/Gate.app

(Thanks Mojca Miklavec for this contribution).

GATE compilation and installation

Recommended configuration

For the 8.1 release, the recommended configuration is the following:

  • Geant4 10.4 (available in http://geant4.web.cern.ch/geant4/support/download.shtml).
    Note that the 8.1 release remains backward compatible with Geant4 10.3 patch 03. The GateRTion 1.0 release, which is very similar to Gate 8.1, can only be built with Geant4 10.03.p03.
  • The CLHEP embedded from Geant4 is available (flag OFF by default). Users can also use the external CLHEP (version 2.3.4.3)
  • gcc 4.8 to 7.3
  • CMake minimal version: 3.3 (with SSL support)
  • CUDA tools to use the GPU modules (available from the NVidia website). Note that the NVCC compiler in version 9.1 seems to have a bug that causes it to crash with a segfault on the current Gate code. According to a report on the gate-user mailing list, CUDA 9.0 works fine with Gate.

Compilation instructions

Validating Installation

If you are able to run Gate after installation by typing

Gate

it is an indication that your installation was successful.

However, before you do any research, it is highly recommended that you validate your installation.

See Validating Installation for benchmarks and further information.

Other Web Sites

G4 Agostinelli S et al 2003 GEANT4 - a simulation toolkit Institute Nucl. Instr. Meth. A506 250-303 GEANT4 website: http://geant4.web.cern.ch

CLHEP - A Class Library for High Energy Physics: http://proj-clhep.web.cern.ch

OGL OpenGL Homepage: http://www.opengl.org/

DAWN release: http://geant4.kek.jp/

ROOT Brun R, Rademakers F 1997 ROOT - An object oriented data analysis framework Institute Nucl. Instr. Meth. A389 81-86 ROOT website: http://root.cern.ch

libxml website: http://www.libxml.org