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:

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 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:

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.
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/..
```
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
```
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:

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

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.

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:

A library or application now relies on files that no longer exist or that didn't exist in the past. For example, this is an example of when the library folder src/OpenFOAM went through too many changes, which makes the build system unable to build as a direct update of the code:
```
+ wmake libso OpenFOAM
/home/ofuser/OpenFOAM/OpenFOAM-dev/src/OpenFOAM
make: *** No rule to make target `/home/ofuser/OpenFOAM/OpenFOAM-dev/platforms/linux64GccDPInt64Opt/src/OpenFOAM/primitives/functions/DataEntry/makeDataEntries.C.dep', needed by `/home/ofuser/OpenFOAM/OpenFOAM-dev/platforms/linux64GccDPInt64Opt/src/OpenFOAM/primitives/functions/DataEntry/makeDataEntries.o'.  Stop.
```
In such a situation, you will need to clean the build folder for this library, which in this case is src/OpenFOAM:
```
wclean libso src/OpenFOAM
```
or:
```
wclean libso $FOAM_SRC/OpenFOAM
```
You can now try building again the source code, as explained in the main chapter Pulling updates and updating the build.
There are too many changes to the source code. For example, if the thermodynamic libraries went through a considerable change in its source code, by adding and renaming files, then all libraries and applications that depend on the thermodynamic libraries will need to be rebuilt after a proper clean up. To do that, it depends on what kind of project you're dealing with:
- If it's OpenFOAM, foam-extend or any other fork/variant, then you can do a complete clean up so that you can rebuild all of the OpenFOAM/foam-extend software, then run:
```
cd $WM_PROJECT_DIR
wcleanAll
```
  You can now try building again the source code, as explained in the main chapter Pulling updates and updating the build.
  Note: Keep in mind that any other applications that you've built that rely on this build the respective OpenFOAM technology (OpenFOAM, foam-extend, etc...), then you will also need to rebuild them, as explained in the next point.
- If it's a community contribution repository, such as swak4Foam, then you will need to go into the folder for its source code and run:
```
wclean all
```
  Then you need to rebuild the source code for this utility once again, for example by running:
```
wmake all
 
#run a second time for getting a summary list of the build
wmake all
```
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

Installation/Working with git repositories

Contents

1 Introduction

2 Installing Git

3 Cloning a repository

4 Pulling updates and updating the build

4.1 What to do if the build process fails