The Unofficial OpenFOAM Cygwin Port: An Overview.

Porting OpenFOAM to Cygwin involves a range of changes, particularly if it's to run on an ordinary (non-"managed") mount which uses the usual Windows case-insensitive filesystem. In order to make the changes clearer to follow, I've divided the changes up into five independent patch files, which are described below, and in more detail in the changelog.cygwin file.

This document assumes that the reader is familiar with OpenFOAM. If you are not, the Official OpenFOAM Home Page is the best place to start.

License

This port, like the official version of OpenFOAM, is licensed under the GNU Public License, version 2.0 or (at your option) any later version. See the distribution files for details.

Credit

The credit for creating OpenFOAM in the first place, and for releasing it as free software, goes to OpenCFD Ltd..

The original port, including resolution of some particularly thorny issues involving compilation order and the complications of the Windows linker, was done by Petr Vita in collaboration with Niklas Nordin and Ron W. Cresswell. Without their work, this port would certainly not have been possible. See Petr's OpenFOAM-Cygwin-HOWTO file for more information.

The much easier work of disambiguating the case-sensitive filenames and making pretty packages was then done by Brooks Moses.

Dependencies

Aside from a reasonably up-to-date Cygwin installation, the following Cygwin packages (beyond those typically installed by default) need to be installed to use a binary distribution:

To build OpenFOAM from source, one also needs:

And, if one wants to work unpack the provided patches:

Current Distributions

The current version of the Cygwin port is OpenFOAM-1.3.cygwin-0.5. To install it, create a OpenFOAM directory in an appropriate place (typically a subdirectory directly off one's user directory; see the offical OpenFOAM installation page for details). The OpenFOAM source distribution should be unpacked into that directory.

OpenFOAM-1.3.cygwin-src-0.5.tar.gz

In addition, a copy of GCC should be installed by unpacking the following GCC tar file into a "cygwin" subdirectory of the OpenFOAM directory. This copy of GCC is compiled with the appropriate flags OpenFOAM (in particular, Petr found that the "--enable-fully-dynamic-string" flag was needed to avoid a critical compiler bug), so this is the simplest way to ensure that OpenFOAM is using the correct version.

gcc-4.1.0.cygwin-OpenFOAM.tar.gz

These two files contain all that is necessary to install OpenFOAM from source; simply go to the top-level OpenFOAM directory, source .OpenFOAM-1.3/cshrc or .OpenFOAM-1.3/bashrc as appropriate, and run ./Allwmake. The compilation time is on the order of two or three hours on a current machine. Alternately, unpacking the following tarball of precompiled binaries into the OpenFOAM directory will produce the same results (aside, of course, from all the intermediate object files):

OpenFOAM-1.3.cygwin-bin-0.5.tar.gz

Finally, to save space, the doc directory has been omitted from the above source package (and all the packages below as well). If you don't have a copy from the official OpenFOAM distribution, you can download this "Docs" package and unpack it in the OpenFOAM directory:

OpenFOAM-1.3.Docs.tar.gz

For example, if you've downloaded the files into your home directory, and are using the bash shell (which is Cygwin's default shell) then you could install them with the following set of commands:

  cd $HOME 
  mkdir OpenFOAM 
  cd OpenFOAM 
  tar -xzf ../OpenFOAM-1.3.cygwin-src-0.5.tar.gz 
  tar -xzf ../OpenFOAM-1.3.cygwin-bin-0.5.tar.gz 
  tar -xzf ../OpenFOAM-1.3.Docs.tar.gz 
  mkdir cygwin 
  cd cygwin 
  tar -xzf ../../gcc-4.1.0.cygwin-OpenFOAM.tar.gz
  cd ..
  source ~/OpenFOAM/.OpenFOAM-1.3/bashrc

Alternately, if you don't want to use the precompiled executable files, you would not unpack the OpenFOAM-1.3.cygwin-bin-0.5.tar.gz file, and would instead run ./Allwmake in the OpenFOAM directory after the source command.

Finally, you should add the source line to your .bashrc file in your root directory, so that it will get run in each terminal window you open. (Alternately, you could just run it by hand each time, before you start using OpenFOAM.)

Past Distributions

There is also a port of OpenFOAM-1.2, with the current version at cygwin-0.7. The installation instructions are the same as for OpenFOAM-1.3, and the relevant files are:

OpenFOAM-1.2.cygwin-src-0.7.tar.gz

gcc-4.0.2.cygwin-OpenFOAM.tar.gz

OpenFOAM-1.2.cygwin-bin-0.7.tar.gz

OpenFOAM-1.2.Docs.tar.gz

If you are currently using OpenFOAM-1.2.cygwin-0.6 and wish to upgrade without downloading the full distribution, you can use this patch file. The changes do not affect the binary files, so there is no need to recompile.

OpenFOAM-1.2.cygwin-src-0.7.diff

Patch Files and Explanation

There is one immediate problem in working with the official OpenFOAM distribution on a Cygwin machine: Unless one uses a managed mount to provide a case-sensitive filesystem, one cannot even unpack the distribution correctly due to filename clashes (e.g., vector.C and Vector.C). Thus, the first distribution package is a tar file which duplicates the official OpenFOAM distribution, except that one of each pair of conflicting files has been renamed with a trailing underscore. A few additional files have been renamed as well, to keep .C and .H pairs consistent, and to avoid some clashes in compilation later on.

There are three basic classes of files that have been renamed with trailing understores to correct for this problem: 23 source files and 4 directories (mostly in the OpenFOAM source proper), 2 data files (in the Xoodles tutorial), and a large number of FoamX files (primarily icons). At this point, this port only deals with the first set; as a result of the others, FoamX and the Xoodles tutorial are non-functional.

This is, however, insufficient to avoid all of the case-insensitivity problems. OpenFOAM uses the .C and .H file extensions to denote C++ files, and a baker's dozen of the various .H files have names identical to standard system .h include files. Ideally, we would avoid this problem entirely by changing all of the OpenFOAM files to .cc and .hh extensions, but this would be a major endeavor and would require changes in all user applications as well. Thus, currently only the conflicting files have been renamed.

Note that at this point, absolutely no changes to the file contents have been made from the official sources; in particular, no #include lines have been altered. This is the "CaseInsensitive" package:

OpenFOAM-1.3.CaseInsensitive.tar.gz (not yet loaded)

The first change is to fix all of the file references that just got broken by renaming files; in particular, #include lines and entries in Make/files configurations. The following patch file (which should be applied to the CaseInsensitive files) includes these changes:

OpenFOAM-1.3.cygwin-src-0.1.diff

Now that the case-sensitivity problems are addressed, we can begin with the real meat of the patch, which comes from Petr and his colleagues. We start with various changes to the cshrc and bashrc scripts in order to add architecture options for the Cygwin environment, and to account for some minor differences in the environment itself.

OpenFOAM-1.3.cygwin-src-0.2.diff

Next, the most important piece of this: the changes to the wmake build system that are required for adapting to the Windows linker. This is explained in considerably more detail in the OpenFOAM-Cygwin-HOWTO.txt file.

The key difficulty is that Windows does not allow .dll files to have unresolved symbols, but OpenFOAM has a dependency loop between the OpenFOAM and Pstream .dll files wherein the compliation of each one depends on symbols defined in .C files belonging to the other. This can be resolved by "importing" the relevant .C files rather than linking to the (not yet extant) .dll when compiling the first library, and then linking the second one to it. The changes to wmake enable this to be done in a simple manner simply by adding appropriate lines to the Make/files file for the files to be "imported". In addition, the wmakeLnInclude script does not properly handle .cc and .hh files, and so it must be adapted to link those as well.

OpenFOAM-1.3.cygwin-src-0.3.diff

The changes to the wmake architecture enable us to fix the dependency loop between Pstream and OpenFOAM; we do that by compiling OpenFOAM (instead of Pstream) first on Cygwin with the Make/files file changes to "import" the three Pstream/dummy files.

There are a number of other small changes that are required on Cygwin with regards to extra #include headers needed, and in one case some function prototypes are needed that didn't exist in the original version, so those are added. Those are included here, along with changes to the build scripts so that MICO and programs that depend on it (FoamX, patchTool, and foamDebugSwitches) are not built on Cygwin.

OpenFOAM-1.3.cygwin-src-0.4.diff

Finally, compilation on Cygwin requires additional libraries to be included at link time instead of being left until runtime, and this requires changes to quite a number of the Make/options files. (In a number of cases, it is the Pstream library that now needs to be linked explicitly. While this might appear to be an effect of reversing the Pstream and OpenFOAM compilation order, it isn't; it occurs when they are compiled and linked in the other order as well.)

OpenFOAM-1.3.cygwin-src-0.5.diff

At this point, the port can be compiled.

Porting User Applications

Porting the base OpenFOAM distribution is, of course, only part of the story, as OpenFOAM is a set of libraries which users can use to write their own applications, and these user applications will also need porting.

Fortunately, the porting process for most of these applications should be quite straightforward. For many applications, no porting work is needed; the program will compile as-is.

In some cases, it may be necessary to include some extra libraries in the Make/options file for compilation on Windows. Have a look at a similar application in the main distribution for an example of what's needed.

In addition, though it appears to luckily be fairly rare, some applications will directly reference one of the files that has been renamed. Thus, check through the lists (which can be conveniently found at the top of the changelog.cygwin file, in the first two sections) and see if any of those 32 files are referenced in your application. If so, change the relevant references. (If you want to avoid breaking compilation on other platforms, surround the changes with "#ifdef cygwin" delimiters.)

Finally, it's possible that a user application may have the same problem as the Xoodles example, and have two variable names which clash. This will unfortunately need to be disambiguated the hard way, at this point, though hopefully the "hard way" will only involve renaming the variable in the relevant IOobject call and changing the data files.


Brooks Moses, 2005-Apr-10