View source for Installation/Working with git repositories

__FORCETOC__

= Introduction =
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 {{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]]


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

= Installing Git =
The official instructions are provided here: [http://git-scm.com/book/en/v2/Getting-Started-Installing-Git Getting Started - Installing Git]

But usually it's just a matter of installing it in your system:
; Linux
: As ''root'' (see [[FAQ/Installation_and_Running#What_is_root_mode.3F|What is ''root'' mode?]]), run:
:* On Debian systems (e.g. Ubuntu and Linux Mint): <bash>apt-get install git-core</bash>
:* On Redhat systems (e.g. Fedora, RHEL, CentOS, SL): <bash>yum groupinstall "Development Tools"</bash> Or: <bash>yum install git</bash>
:* On Suse systems (e.g. OpenSUSE): <bash>zypper install git</bash>

; Mac OS X
: The official version for Mac OS X: [http://git-scm.com/download/mac Git for Mac OS X at git-scm.com]

; Windows
: The official version for Windows: [http://git-scm.com/download/win Git for Windows at git-scm.com]
: msysGit: [http://msysgit.github.io/ msysGit at msysgit.github.io]

= Cloning a repository =
Usually this is pretty straight forward:
<ol>
<li>Make sure you already have {{tt|git}} installed, for example, by running:
<bash>git --version</bash>
If it's installed, it should state something like:
<bash>git version 1.7.9.5</bash>
'''Note''': If it's not installed yet, then go back to the chapter [[#Installing Git|Installing Git]].
</li>

<li>Now find a good place (path) to clone the repository into, for example:
<ul {{NoIndentStyle}}>
<li>If it's OpenFOAM, then the usual path is {{tt|~/OpenFOAM}}. You can create the folder (if it doesn't exist yet) and go into it by running:
<bash>cd ~
mkdir OpenFOAM
cd OpenFOAM</bash>
</li>

<li>If it's foam-extend, then the usual path is {{tt|~/foam}}. You can create the folder (if it doesn't exist yet) and go into it by running:
<bash>cd ~
mkdir foam
cd foam</bash>
</li>

<li>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:
<bash>mkdir -p $FOAM_RUN
cd $FOAM_RUN/..</bash>
</li>
</ul>
</li>

<li>Next, it's just a matter of cloning the repository, for example:
<bash>git clone http://github.com/OpenFOAM/OpenFOAM-2.4.x.git</bash>
Or also include the target path where you want to clone into, for example:
<bash>git clone git://git.code.sf.net/p/openfoam-extend/foam-extend-3.1 foam-extend-3.1</bash>
</li>

<li>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:
<bash>cd OpenFOAM-2.4.x</bash>
Or:
<bash>cd foam-extend-3.1</bash>
</li>
</ol>

= 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:
<ol>
<li>Go into the folder where the source code is located. Some examples:
<bash>foam
cd $WM_PROJECT_DIR
cd ~/foam/foam-extend-3.1
cd $FOAM_RUN/../swak4Foam</bash>
</li>

<li>Now ''pull'' the updates by running:
<bash>git pull</bash>
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>If the ''pull'' occurred without any error messages, then you can proceed with building the source code once again:
<bash># 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
</bash>
</li>
</ol>

Now have a look at the contents of the file {{tt|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|What to do if the build process fails]]

== What to do if the build process fails ==

There are essentially three scenarios of ''build failure'' after a successful {{tt|git pull}}:
<ol>
<li>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 {{tt|src/OpenFOAM}} went through too many changes, which makes the build system unable to build as a direct update of the code:
<bash>+ 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.
</bash>
In such a situation, you will need to clean the build folder for this library, which in this case is {{tt|src/OpenFOAM}}:
<bash>wclean libso src/OpenFOAM
</bash>
or:
<bash>wclean libso $FOAM_SRC/OpenFOAM
</bash>
You can now try building again the source code, as explained in the main chapter [[#Pulling updates and updating the build|Pulling updates and updating the build]].
</li>

<li>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:
<ul {{NoIndentStyle}}>
<li>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:
<bash>cd $WM_PROJECT_DIR
wcleanAll
</bash>
You can now try building again the source code, as explained in the main chapter [[#Pulling updates and updating the build|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.
</li>

<li>If it's a community contribution repository, such as [[Contrib/swak4Foam|swak4Foam]], then you will need to go into the folder for its source code and run:
<bash>wclean all</bash>
Then you need to rebuild the source code for this utility once again, for example by running:
<bash>wmake all

#run a second time for getting a summary list of the build
wmake all</bash>
</li>
</ul>

</li>

<li>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.
</li>
</ol>


If after assessing the previous 3 scenarios there are still errors, then check the examples listed here: [[FAQ/Installation_and_Running#Common_errors_when_building_OpenFOAM_from_source_code|Common errors when building OpenFOAM from source code]]


[[Category:Installing OpenFOAM - Other Details]]