TestFloquation

1 Sandbox

1.1 Math

My in-line equation is: $y_1=e^{x^2}$ And on its own line:

 $y_2=\sqrt{e^{x^2}}$

It then follows that we have two equations. Q.E.D.

1.2 Version

Valid versions:

1.3 Links

LinkName to Main Page

1.4 Subpages

1.4.1 Subsection: Subpages of Contrib

1.5 Images

alt text3

2 Tutorial preparation: Enabling symbol recognition and autocompletion in Eclipse by fooling the indexer

How OpenFOAM includes pEqn.H in a solver

OpenFOAM #include-s many lines of code in a copy-paste manner, e.g. “createTime.H” and “UEqn.H” in many solvers. These included files are not actual C-headers in the “normal” sense. Their sole purpose is to distribute executable lines of code over multiple files for readability and reusability. This method allows OpenFOAM to define reusable local variables. They are typically included in the middle of the code, rather than at the top of a file (like a “normal” C-header). Take for example “pEqn.H” in the “interFoam” solver (in the figure on the right hand side).

Eclipse's indexer does not understand this way of using headers, because it is considered bad-style. (Despite this, it is a really convenient thing to do in OpenFOAM.) The compiler does, however, understand it: It is allowed in C++. Therefore, your code will compile, whereas Eclipse tells you there are numerous errors:

Luckily, up to a certain degree, we can fool the indexer by feeding it with more information. This will solve many problems, although not all of them.

3 Advantages / Disadvantages

The method I am about to describe has both advantages and disadvantages. Judge for yourself whether you think the advantages outweigh the disadvantages. Please do note that nothing we do to the indexer will change the functioning of your code, as the compiler is responsible for that – not the indexer.

The advantages are:

Eclipse will no longer give you errors for correct things inside your C file, e.g. “interFoam.C”.
Symbols will be recognized, allowing you to use the (Navigate -> Open Declaration (F3)) function to jump to its declaration.
Methods/Functions will be recognized, allowing you to use F3 once again.
You will be able to use the autocompletion function while programming.

The disadvantages are:

Eclipse will still give you “Syntax errors” inside the included header files (like UEqn.H). Autocompletion does not work, although F3 does behave decently. (Note that everything works if the included file is copied into the C file – which is particularly useful if you are developing a new code.)
It is relatively labor-intensive to set it up. (But luckily you only have to do it once for a given project, and the "pro tips" section below gives tips on how to do it a lot faster.)
Fooling the indexer to understand the code may cause the indexer to understand code which cannot be compiled. This may happen when included variables are used outside their scope: The deceived indexer will no longer be able to tell you when the variables are out of scope, as they will be treated as global variables.
Similar to the above problem, there may be other unexpected consequences of fooling the indexer, which are unknown at the time of writing.

4 Before we start

First follow these steps to import your code into Eclipse. For the exemplifying figures below, “Eclipse Mars.1 (4.5.1)” with “CDT 8.8.1” is used. Then, (a copy of) “interFoam v2.3.x” will be imported into Eclipse. My indexer settings (Window->Preferences->C/C++->Indexer) are as follows:

4.1 Copying interFoam

Copying “interFoam” can be quickly done as follows (Linux, ). This assumes that the OpenFOAM environment has been sourced in the terminal:

$ cd $FOAM_USER_SOLVERS 
$ cp -r $FOAM_SOLVERS/multiphase/interFoam ./interFoam_EclipseTut
$ cd interFoam_EclipseTut
$ 'rm' -r interDyMFoam interMixingFoam LTSInterFoam porousInterFoam Allwmake Allwclean
$ wclean

Now replace references to APPBIN to USER_APPBIN, but first see if behaviour is as expected:

$ grep -lre "FOAM_APPBIN" . | xargs -l sed -e 's/FOAM_APPBIN/FOAM_USER_APPBIN/g'

If the behaviour is as expected, then actually search-and-replace:

$ grep -lre "FOAM_APPBIN" . | xargs -l sed -i -e 's/FOAM_APPBIN/FOAM_USER_APPBIN/g'

Similarly for the name of “our” solver:

$ grep -lre "interFoam" . | xargs -l sed -e 's/interFoam/interFoam_EclipseTut/g'
$ grep -lre "interFoam" . | xargs -l sed -i -e 's/interFoam/interFoam_EclipseTut/g'
$ mv interFoam.C interFoam_EclipseTut.C

And finally test if it still compiles (and clean right after):

$ wmake && ls $FOAM_USER_APPBIN && wclean

4.2 Including directories

Then, in the case of “interFoam”, add the following include directories (Project->Properties->C/C++ General->Paths and Symbols), as described here:

This will enable Eclipse's indexer to find all included headers (see the following figure). It will, however, not recognize all symbols yet. We must first feed the indexer with more information.

Eclipse interFoam EclipseTut justLoaded.png

5 Fooling the indexer

It is impossible to have Eclipse's indexer understand what is going on. We can, however, trick it to make it think it understands. The downside is of course that just like any human being who thinks he/she understands whereas he/she does not: it is bound to make some mistakes (see the disadvantages).

The trick is to manually include the files holding the declarations of the variables (e.g. “createTime.H”) in the preprocessor. This will trick the indexer to think that the declared variables are global variables in the project. So the indexer effectively loses the concept of “variable scope”. In the case of a solver, this is perfectly fine: all variables are in effect global variables anyway!

First, go to (Window->Preferences->C/C++->Property Pages Settings) and tick the box 'Display “Include Files” tab on Paths and Symbols page':

Eclipse WindowPreferences IncludeFiles.png

Now go to (Project->Properties->C/C++ General->Paths and Symbols->Include Files) and add all header files which Eclipse is complaining about. Do not forget to rebuild the index. For example, add “createTime.H” for the variable “runTime” to be recognized:

Note that the method “run” from the variable “runTime” is not yet recognized. (Actually, no method will be recognized.) For it to be recognized, “Time.H” must also be added. Or rather: “fvCFD.H” must be added, because this is the file which includes “Time.H” in our project. “fvCFD.H” must be included before “createTime.H”. I am not sure why the order matters, but it is probably because “fvCFD.H” includes “Time.H”, which must be known before “createTime.H” is interpreted.

Continuing this process for all errors, we eventually end up with the following list of includes. (Note that the order does again matter for some files.)

Including “pEqn.H” and “UEqn.H” is optional. It is required to make the variable “UEqn” and “pEqn” known in the C-file, but it is not required to remove the errors in the case of “interFoam”, because “interFoam” does not use those variables in the C-file. The final result is then:

Now, in your “UEqn.H”, “pEqn.H” and “createFields.H” you will still see “Syntax error”. I do not yet know how to solve this issue. If you do know, please share it with the rest of us. Also, as was mentioned in the disadvantages, you will not have autocompletion within these files, and F3 works only partially (it shows a list of possible functions, rather than picking the correct function by itself). In your C-file, however, everything works perfectly (as can be seen in the figure above). Now, if you'd copy the content of e.g. “UEqn.H” into your C file, it is fully functional: both autocompletion and F3 work flawlessly. Although it is not completely convenient to do so, this does permit us to use Eclipse's powerful features.