Difference between revisions of "Installation/Working with git repositories"

From OpenFOAMWiki
(Pulling updates and updating the build: Save before something happens... still have to fill in the TODO entries)
m (changed references to git to <tt> formatting)
Line 2: Line 2:
  
 
= Introduction =
 
= Introduction =
This page attempts to introduce the reader to getting familiar with how to handle git repositories that are related to OpenFOAM and building the source code provided by those repositories. This page does '''not''' attempt to:
+
This page attempts to introduce the reader to getting familiar with how to handle {{tt|git}} repositories that are related to OpenFOAM and building the source code provided by those repositories. This page does '''not''' attempt to:
# teach how to use git in detail, because there are a lot of tutorials and books available for that, which some are already listed in [[Tip Starting points for using GIT]];
+
# teach how to use {{tt|git}} in detail, because there are a lot of tutorials and books available for that, which some are already listed in [[Tip Starting points for using GIT]];
 
# teach you on how to use the shell/command line, because there is already a page that does that: [[Installation/Working with the Shell]]
 
# teach you on how to use the shell/command line, because there is already a page that does that: [[Installation/Working with the Shell]]
  
Line 29: Line 29:
 
Usually this is pretty straight forward:
 
Usually this is pretty straight forward:
 
<ol>
 
<ol>
<li>Make sure you already have git installed, for example, by running:
+
<li>Make sure you already have {{tt|git}} installed, for example, by running:
 
<bash>git --version</bash>
 
<bash>git --version</bash>
 
If it's installed, it should state something like:
 
If it's installed, it should state something like:
Line 82: Line 82:
 
<li>Now ''pull'' the updates by running:
 
<li>Now ''pull'' the updates by running:
 
<bash>git pull</bash>
 
<bash>git pull</bash>
If this command gives you problems, then you better go study how you can use git (e.g. [[Tip Starting points for using GIT]]), because several possible errors can happen.
+
If this command gives you problems, then you better go study how you can use {{tt|git}} (e.g. [[Tip Starting points for using GIT]]), because several possible errors can happen.
 
</li>
 
</li>
  

Revision as of 17:40, 26 July 2015


1 Introduction

This page attempts to introduce the reader to getting familiar with how to handle git repositories that are related to OpenFOAM and building the source code provided by those repositories. This page does not attempt to:

  1. teach how to use git in detail, because there are a lot of tutorials and books available for that, which some are already listed in Tip Starting points for using GIT;
  2. teach you on how to use the shell/command line, because there is already a page that does that: Installation/Working with the Shell


The text may seem rather informal, so feel free to add to and improve this wiki page!

2 Installing Git

The official instructions are provided here: Getting Started - Installing Git

But usually it's just a matter of installing it in your system:

Linux
As root (see What is root mode?), run:
  • On Debian systems (e.g. Ubuntu and Linux Mint):
    apt-get install git-core
  • On Redhat systems (e.g. Fedora, RHEL, CentOS, SL):
    yum groupinstall "Development Tools"
    Or:
    yum install git
  • On Suse systems (e.g. OpenSUSE):
    zypper install git
Mac OS X
The official version for Mac OS X: Git for Mac OS X at git-scm.com
Windows
The official version for Windows: Git for Windows at git-scm.com
msysGit: msysGit at msysgit.github.io

3 Cloning a repository

Usually this is pretty straight forward:

  1. Make sure you already have git installed, for example, by running:
    git --version

    If it's installed, it should state something like:

    git version 1.7.9.5

    Note: If it's not installed yet, then go back to the chapter Installing Git.

  2. Now find a good place (path) to clone the repository into, for example:
    • If it's OpenFOAM, then the usual path is ~/OpenFOAM. You can create the folder (if it doesn't exist yet) and go into it by running:
      cd ~
      mkdir OpenFOAM
      cd OpenFOAM
    • If it's foam-extend, then the usual path is ~/foam. You can create the folder (if it doesn't exist yet) and go into it by running:
      cd ~
      mkdir foam
      cd foam
    • If it's a community contribution repository (e.g. those listed at Contrib), then the advisable path is the dedicated user folder for the version of OpenFOAM technology you're using. You can create said folder (if it doesn't exist yet) and go into it by running:
      mkdir -p $FOAM_RUN
      cd $FOAM_RUN/..
  3. Next, it's just a matter of cloning the repository, for example:
    git clone http://github.com/OpenFOAM/OpenFOAM-2.4.x.git

    Or also include the target path where you want to clone into, for example:

    git clone git://git.code.sf.net/p/openfoam-extend/foam-extend-3.1 foam-extend-3.1
  4. If no error messages appear, then you're good to go! The next step is to go into the folder you've just finished cloning, for example:
    cd OpenFOAM-2.4.x

    Or:

    cd foam-extend-3.1

4 Pulling updates and updating the build

The standard procedure for pulling the latest updates from a repository and them updating the build is usually pretty simple:

  1. Go into the folder where the source code is located. Some examples:
    foam
    cd $WM_PROJECT_DIR
    cd ~/foam/foam-extend-3.1
    cd $FOAM_RUN/../swak4Foam
  2. Now pull the updates by running:
    git pull

    If this command gives you problems, then you better go study how you can use git (e.g. Tip Starting points for using GIT), because several possible errors can happen.

  3. If the pull occurred without any error messages, then you can proceed with building the source code once again:
    # This next command will take a while... could take any time between 30 minutes to 3-6 hours.
    ./Allwmake > log.make 2>&1
     
    #Run it a second time for getting a summary of the installation
    ./Allwmake > log.make 2>&1

Now have a look at the contents of the file log.make:

  • If there are no error messages in the build process, then everything should be ready to be used.
  • On the other hand, if there are error messages in the build, then check the section What to do if the build process fails

4.1 What to do if the build process fails

There are essentially three scenarios of build failure after a successful git pull:

  1. A library or application now relies on files that no longer exist or that didn't exist in the past. TODO
  2. There are too many changes to the source code. TODO
  3. The repository is missing some of the new code that was meant to be there. This usually occurs if the previous scenario fails to give a successful build. If this is the case, you should report the issue on the respective project's bug/issue tracker.


If after assessing the previous 3 scenarios there are still errors, then check the examples listed here: Common errors when building OpenFOAM from source code