OpenFOAM Linux Guide

This guide provides information and example terminal commands for Linux, relevant to users of OpenFOAM.  Commands are written that refer to OpenFOAM, e.g. they include OpenFOAM Linux environment variables.  Those commands that refer to OpenFOAM will only function as stated, if they are executed on a machine on which OpenFOAM is installed and the user’s environment variables are set up for OpenFOAM, e.g. as described in the source download page (see Setting Environment Variables).

Environment variables

Linux uses environment variables that specify a set of values that affect the way the computer runs.  The OpenFOAM configuration sets environment variables mainly to provide short-cuts in the use of OpenFOAM and to help with compilation of OpenFOAM.  The short-cut environment variables generally begin FOAM_ whereas the compilation environment variables begin WM_.

env	List all environment variables in the shell (terminal)
env | grep ^FOAM_	List environment variables beginning FOAM_
echo $FOAM_SRC	Return the value (denoted by $...) of the FOAM_SRC environment varaible

Navigation

From the terminal, you can navigate around the file system, where files are organised in a tree of directories (folders).  The home or top directory on the user’s file system is specified through the HOME environment variable, often /home/ (check by typing echo $HOME). The root directory of the entire filing system, including system files is typically denoted by / The current directory you are in is denoted by . The directory one level higher than the current directory is denoted by ..

pwd	Print the current directory (find out which directory you are in)
cd ~	Changes directory to home directory (~ is a short-cut meaning $HOME)
cd constant	Change to a directory named constant in the current directory
cd ..	Move up one directory

Directory listing

ls	List files in the current directory
ls /etc	List files in the /etc directory (a system directory)
ls -a	List all files, including hidden files beginning with ., e.g. .bashrc
ls -l	List with long list format that includes file ownership and permissions
ls -al	List all files with long list format

Create, copy, move and delete files and directories

Data is stored in files and with the filing system managing the names and hierarchies of files and directories. The copy command (cp) copies file data to a file with a new name. The move command (mv) simply renames a file or directory, or alters its location in the directory hierarchy, so involves no writing of file data.

echo "Hello World" > file1.txt	Create a new file file1.txt containing the text Hello World
mkdir newDir	Create a new directory newDir
cp file1.txt file2.txt	Create a new file file2.txt by copying file1.txt
mv file2.txt newDir1/	Move file2.txt into newDir directory
cp -r newDir1 newDir2	Copy directory and contents (-r = “recursively”) of newDir1 to a new directory newDir2
mv file1.txt file3.txt	Rename file1.txt, e.g. file3.txt
rm file3.txt	Delete file3.txt
rm -rf newDir1	Delete newDir1 directory and contents
cp newDir2/file2.txt file1.txt	Copy file2.txt from newDir1 directory to file1.txt in the current directory

Printing  to terminal

Sometimes it can be useful to print text files to the terminal.

cat file1.txt	Print the file1.txt file to terminal
less $WM_PROJECT_DIR/Allwmake	Scroll through the Allwmake file in terminal; type <SPACE> to scroll, Q to quit
head -10 $WM_PROJECT_DIR/Allwmake	Print the first 10 lines of Allwmake
tail -5 $WM_PROJECT_DIR/Allwmake	Print the last 10 lines of Allwmake

Expression matching

It can be useful to search through files for expressions using the grep command.

grep -h build $WM_PROJECT_DIR/Allwmake	-h: Prints lines of file Allwmake that contain the expression build
grep -h -i BuIlD $WM_PROJECT_DIR/Allwmake	-i: Prints lines of file Allwmake that contain BuIlD, ignoring upper/lower case
grep -l if $WM_PROJECT_DIR/Allwmake	-l: Prints the filename Allwmake to terminal if it contains the expression build
grep -H if $WM_PROJECT_DIR/Allwmake	-H: Prints both filename and lines of a file that contain an expression the expression

Finding files/directories

The find command allows us to search quickly through files in the filing system.

find $FOAM_SRC	Prints all files, directories and links in the OpenFOAM src directory (FOAM_SRC)
find $FOAM_SRC -name fvMesh.H	Prints files and links (or directories) named fvMesh.H in FOAM_SRC
find $FOAM_SRC -name fvMesh.H -type f	Prints files only named fvMesh.H in FOAM_SRC
find $FOAM_SRC -name fvMesh.H -type l	Prints links only named fvMesh.H in FOAM_SRC
find $FOAM_SRC -name "*.[CH]" -type f	Prints files only ending .H or .C in FOAM_SRC (* means “any characters”)

Searching for an expression in a large number of files

Combining find and grep allows us to search for an expression in large number of files. For example to search through all OpenFOAM .C source files to find one containing the expression kepsilon (case insensitive):

find $FOAM_SRC -name "*.C" | xargs grep -l -i kepsilon

An alternative syntax, that executes slower is:

find $FOAM_SRC -name "*.C" -exec grep -l -i kepsilon {} \;

Process handling

When something is typed terminal command line, a process (or job) is executed. For example, we may wish to execute a process that runs a text editor called gedit. We could open the Allwmake file mentioned earlier by typing

gedit $WM_PROJECT_DIR/Allwmake

This starts the gedit application in the foreground of the terminal window. We now have no control over the command line prompt in the window. One way to regain control is to shut down the editor; a brute force way to do this, is to hit <CTRL-C> in the terminal to kill the process.

Alternatively we could keep the process alive and hit <CTRL-Z> in the terminal. This will stop the process, allowing us to regain control over the command prompt. From there we could restart the process in the foreground by typing fg in the terminal, in which case we lose the terminal prompt again. Alternatively we can restart the process in the background by typing bg, allowing both gedit to run and taking control of the prompt.

If we wish to execute gedit in the background from the start we can add an & to the command line on execution, i.e.

gedit $WM_PROJECT_DIR/Allwmake &

Information about running processes can be displayed by typing

ps

The output display a process ID number (PID). The process can be killed using the kill command. It sends a signal to the process with specified PID where the -9 option will cause the process to be killed. For example, to kill the process with PID 2222:

kill -9 2222

The killall command can kill all gedit processess, e.g.

killall -9 gedit

Other useful commands to display running processes are top (kill with <CTRL-C>) and jobs