This pages gives a broad overview on how to obtain and install
ughub
and how to use it to obtain
UG4.
It also provides a brief introduction on how to build UG4 on
Linux, Mac-OSX and Windows. You can select the appropriate tab
below to view the instructions for your operating system.
You should be able to use your default terminal application to execute the commands below.
ughub requires Python to run (at least version 2.6 should be available, higher is recommended). Please make sure that Python is installed by executing the following command:
python --version
If it is not installed yet, please install it through your package manager if your on Linux. On Mac-OSX, you can download and install it from
https://www.python.org/downloads/
Please also make sure that git is installed on your system and that it can be invoked from your terminal or shell.
You will need cmake to generate the build files for your compiler. You may install with your package manager on Linux or from
Please clone the GitHub repository, e.g. by executing the following commands:
cd $HOME
git clone https://github.com/UG4/ughub
This will download ughub to $HOME/ughub. You may
of course clone the repository to any other location. Simply
replace $HOME/ughub with your path for the
remainder of this introduction.
Please make sure to update your ughub installation from time to time by executing
cd $HOME/ughub
git pull
ughub should run out of the box. However, in order to execute
it from any path, you should either edit your PATH environment
variable by adding the following line to your
$HOME/.bash_profile or
$HOME/.bashrc file
export PATH=$PATH:$HOME/ughub
or create a link to $HOME/ughub/ughub from within
a path which is already contained in your PATH variable, e.g.,
like this
cd $HOME/bin
ln -s $HOME/ughub/ughub ughub
If you choose to edit your PATH variable, please make sure to
reload your .bash_profile or
.bashrc files, e.g.:
source $HOME/.bash_profile
If you are interested in using auto-completion (in bash) while
using ughub, add the following additional line to your
$HOME/.bash_profile or
$HOME/.bashrc file
source $HOME/ughub/autocompletions/ughub-completion.bash
and reload the file. Alternatively, you can place this line in
~/.bash_completion. To use this in zsh, you need
to use bashcompinit, see
here.
Autocomplete is also available for fish. To use this, copy
autocompletions/ughub-completion.fish to
~/.config/fish/completions/ughub.fish (and reload
your fish instance).
You may use the pre-installed command line tool
cmd.exe. If you’re using Microsoft Visual Studio you
may instead use the
VS2015 x64 Command Prompt (64bit) or the
VS2013 x86 Command Prompt (32bit) (or similar).
Both can be found in
'Start -> All Programs -> Visual Studio 2015'
ughub requires Python to run (at least version 2.6 should be available, higher is recommended). Please make sure that Python is installed by executing the following command:
py --version
If it is not installed, please download and install it from
https://www.python.org/downloads/
Please also make sure that git is installed on your system and that it can be invoked from your terminal or shell.
You will need cmake to generate the build files for your compiler. You may install it from
Please clone the github repository, e.g. by executing the following commands:
cd %HOMEPATH%
git clone https://github.com/UG4/ughub
This will download ughub to %HOMEPATH%/ughub. You may of course clone the repository to any other location. Simply replace %HOMEPATH%/ughub with your path for the remainder of this introduction.
Please make sure to update your ughub installation from time to time by executing
cd %HOMEPATH%/ughub
git pull
ughub should run out of the box on Windows. However, in order to execute it from any path, you should add
$HOME/ughub
to your Path environment variable (replace $HOME with the actual path). In order to do so, enter
SystemPropertiesAdvanced
in your shell. This opens the System Properties dialog and highlights the Advanced tab. Click the Environment Variables button at the bottom of the dialog. This opens a dialog which lets you edit the Path variable. Note that paths are separated by a semicolon ‘;’. If the old value of your Path variable was SomePaths, the new content should look somewhat like this:
SomePaths;C:\Users\YOURNAME\ughub
When you’re done, press ‘OK’ to close the dialog. Make sure to restart your Shell in order to apply the changes.
Autocompletion on windows only works in powershell. To use it, add the line
C:\Users\YOURNAME\ughub\autocompletions\ughub-completion.ps1
to the file (you might need to create it)
C:\Users\YOURNAME\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1
If you wish to use it, you need to allow powershell scripts to execute. Execute the following in an PowerShell session executed as Administrator:
Set-ExecutionPolicy -ExecutionPolicy Unrestricted
Take a look at this to learn about powershell profiles and execution policy.
ughub serves as a package management tool for the UG4 simulation framework. Use the following command to get some help on ughub’s usage:
ughub help
One typically starts by creating a directory into which all UG4 related packages shall be installed (again, the exact path is arbitrary):
cd $HOME
mkdir ug4
Now we can initialize this directory for usage with ughub:
cd $HOME/ug4
ughub init
This creates a local CMakeLists.txt file and creates a hidden
folder .ughub in which package-sources are
maintained. All further calls to ughub from within the directory
tree located at $HOME/ug4 will now relate to this main directory.
To view a list of available packages, execute
ughub list
or ughub listpackages. Which and how many packages
are displayed depends on the registered package-sources. To view
all registered sources execute
ughub listsources
To install a package, simply execute
ughub install with one or more of the available
packages:
ughub install Examples
Dependent packages will now be automatically installed.
In order to add new package-sources, ughub provides the command
addsource. Theoretically, anybody can create new
package-sources and host them e.g. on github. UG4’s public
package-source is hosted at
https://github.com/UG4/ug4-packages
This is ughub’s default source and always registered upon
execution of ughub init. Feel free to clone it, to
add your publicly available packages and to place a merge request.
For a more detailed introduction to ug4’s build settings and to ug4 in general, please also refer to ug4’s manual:
In order to build UG4, you’ll need a C++ compiler (e.g. g++ or clang) and cmake.
Before compiling UG4, please add the following line to your
$HOME/.bashrc or
$HOME/.bash_profile file:
source $HOME/ug4/ugcore/scripts/shell/ugbash
and reload your .bashrc or .bash_profile files, e.g.:
source $HOME/.bash_profile
This feature is not yet supported for Windows.
First create a build directory:
cd $HOME/ug4
mkdir build
cd build
Then simply run cmake:
cmake -DCMAKE_BUILD_TYPE=Release ..
The Microsoft Visual C++ compiler is recommended for compilation of ug4 on Windows. It can be downloaded as part of the free “Express 2015 for Windows Desktop” edition of Visual Studio (download here).
To allow for parallel compilation in the terminal one can optionally use the tool jom. Extract it and add the path in which the executable lies to your Path environment variable.
First create a build directory:
cd $HOME/ug4
mkdir build
cd build
Make sure that you’re running the
VS2015 x64 Command Prompt (or similar).
In order to initialize your build please run
cmake -G "NMake Makefiles JOM" -DCMAKE_BUILD_TYPE=Release -DSTATIC_BUILD=ON ..
or
cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DSTATIC_BUILD=ON ..
depending on whether you installed JOM or not. Alternatively one could also generate Visual Studio Project files. However, this option is not discussed further in this introduction.
Note that static linking should be enabled by default on Windows. If you’d like to build a dynamic library, please have a look at ug4’s documentation.
Each time you’ll execute cmake on your ug4 folder, a list of
installed plugins will be shown. In order to activate an installed
plugin, specify the cmake option -DPLUGIN_NAME=ON,
e.g.:
cmake -DConvectionDiffusion=ON .
You may also activate or deactivate all installed plugins at once:
cmake -DENABLE_ALL_PLUGINS=ON .
cmake -DDISABLE_ALL_PLUGINS=ON .
Some options speed up compilation considerably. E.g. if you only consider problems in two and three dimensional space and only need scalar matrix coefficients, you may use the following cmake options:
cmake -DDIM="2;3" -DCPU=1 .
CMake only prepares the build-settings. To actually build UG4 you’ll have to execute the build command.
To start compiling execute
make -j2
To start compiling execute
jom
or
nmake