Platform Specific Installation Issues
Keywords: userguide

Next: Quick Start: Example OOMMF Up: Installation Previous: Advanced Installation
Subsections

- Unix Configuration
  - Missing Tcl/Tk files
  - Compiler Optimization Options
  - Portland Group pgCC compiler on Linux
- Mac OS X Configuration
- Microsoft Windows Options
  - Using Microsoft Visual C++
  - Using MinGW g++
  - Using the Cygwin toolkit
  - Using Borland C++
  - Using Digital Mars C++
  - Setting the TCL_LIBRARY environment variable

##
Platform Specific Installation Issues

The installation procedure discussed in the previous sections applies to all platforms (Unix, Windows, Mac OS X). There are, however, some details which pertain only to a particular platform. These issues are discussed below.

### Unix Configuration

#### Missing Tcl/Tk files

The basic installation procedure should be sufficient to install OOMMF on most Unix systems. Sometimes, however, the build will fail due to missing Tcl header files (`tcl.h`, `tk.h`) or libraries (e.g., `libtcl.so`, `libtk.so`). This problem can usually be solved by installing a ``development'' version of Tcl/Tk, which may be found on the operating system installation disks, or may be available from the system vendor. There are also binary releases of Tcl/Tk for a number of systems available from ActiveState, under the name ActiveTcl. Alternatively, one may download the sources for Tcl and Tk from the Tcl Developer Xchange, and build and install Tcl/Tk from source. The Tcl/Tk build follows the usual Unix `configure`, `make`, `make install` build convention.

#### Compiler Optimization Options

On most systems, OOMMF builds by default with relatively unaggressive compiler optimization options. As discussed earlier (under Optimization), you may edit the appropriate `oommf/config/platforms/` file to change the default compilation options. However, on some common systems (e.g., Linux, some BSD variants) OOMMF will try to deduce the hardware architecture (i.e., the CPU subtype, such as Pentium 3 vs. Pentium 4) and apply architecture-specific options to the compile commands. This is probably what you want if OOMMF is to be run only on the system on which it was built, or if it is run on a homogeneous cluster. If, instead, you intend to run OOMMF on a heterogeneous cluster you may need to restrict the compiler options to those supported across your target machines. In that case, open the appropriate configuration file in the `oommf/config/platforms/` directory, and look for the lines

        # You can override the GuessCPU results by directly setting or
        # unsetting the cpuopts variable, e.g.,
        #
        #    set cpuopts [list -march=athlon]
        # or
        #    unset cpuopts
        #

Uncomment either the ``unset cpuopts'' line to make a generic build, or else edit the ``set cpuopts'' line to an appropriate common-denominator architecture and uncomment that line.

In a similar vein, some compilers support a ``-fast'' switch, which usually creates an architecture-specific executable. The same considerations apply in this case.

An advanced alternative would be to define separate OOMMF ``platforms'' for each CPU subtype in your cluster. At a minimum, this would involve creating separate platform name files in `oommf/config/names/` for each subtype, and then making copies of the appropriate `oommf/config/platforms` file for each new platform. The platform name files would have to be written so as to reliably detect the CPU subtype on each machine. See ``Managing OOMMF platform names'' for details on creating platform name files.

#### Portland Group pgCC compiler on Linux

The platform build scripts for Linux, `oommf/config/platforms/lintel.tcl` (32-bit) and `oommf/config/platforms/linux-x86_64.tcl` (64-bit) contain sections supporting the Portland Group pgCC compiler. Non-threaded builds of OOMMF using this compiler run fine, but threaded builds segfault when running `Oxsii`/`Boxsi`. The source of this problem is not known at this time.

###
Mac OS X Configuration

The build procedure for Mac OS X is the same as for Unix. The platform name is ``darwin''. If the platform configuration check does not find a C++ compiler, then you will have to install one. One option is the Xcode command line developer tools provided by Apple. You can install these from a Terminal window via the command

    xcode-select --install

You should run this command even if you install the full Xcode IDE. Refer to your system documentation for details.

###
Microsoft Windows Options

This section lists installation options for Microsoft Windows.

####
Using Microsoft Visual C++

If you are building OOMMF software from source using the Microsoft Visual C++ command line compiler, `cl.exe`, it is necessary to set up the path and some environment variables before running the compiler. There is a batch file distributed with Visual C++ that you can run to do this. The name of the file varies between Visual C++ releases, but for example may be `vcvarsall.bat` or `setenv.cmd`. For 64-bit builds you may need to include the ``amd64'' option on the batch file command line. You may want to set up your system so this batch file gets run automatically when you open a command window. See your compiler and system documentation for details.

####
Using MinGW g++

Both 32-bit and 64-bit builds are supported using the MinGW ports of g++. (The 32-bit and 64-bit versions of g++ are separate downloads.) Use a standard Windows Tcl/Tk, such as the ActiveTcl release from ActiveState. You will also need to edit the appropriate platform file to select g++ as the compiler. If you are using a 32-bit Tcl/Tk and g++, then the platform file is `oommf`\`config`\`platforms`\`wintel.tcl`. For 64-bit Tcl/Tk and g++ the platform file is `oommf`\`config`\`platforms`\`windows-x86_64.tcl`.

####
Using the Cygwin toolkit

The Cygwin Project is a free port of the GNU development environment to Windows, which includes the GNU C++ compiler g++ and X11. To build OOMMF within the Cygwin environment, start up a Cygwin or Cygwin64 shell and follow the usual Unix build procedure. The platform name will be `cygtel` or `cygwin-x86_64`, according to whether you are running a 32- or 64-bit Cygwin `tclsh`, respectively. The resulting OOMMF build requires the Cygwin environment to run, so it will need to be launched from a Cygwin shell. Moreover, OOMMF on Cygwin uses X11 as the windowing interface, so you will need to have the Cygwin port of X11 installed; typically OOMMF will be started from an X11 xterm or equivalent. Of course, you will also need the Tcl and Tk packages installed (called `tcl` and `tcl-tk`, respectively, by the Cygwin package manager). To build OOMMF from source you will need the `gcc-g++`, `tcl-devel`, and `tcl-tk-devel` packages and dependencies.

If you get errors saying a child process couldn't be forked (typically with either ``resource temporarily unavailable'' or ``Loaded to different address'' error messages), then follow this procedure:

1. Exit all Cygwin processes
2. Use Windows Explorer or a Windows command shell to launch `c:`\`cygwin`\`bin`\`ash.exe`
3. Run `/bin/rebaseall` inside the ash shell.

Additional information on this problem can be found in the Cygwin documentation.

The Cygwin versions of Tcl/Tk prior to 8.6 were not threaded, so OOMMF built with Tcl/Tk 8.5 and older will likewise not be threaded. This limitation is removed with the Cygwin Tcl/Tk 8.6 release.

####
Using Borland C++

OOMMF has been successfully built and tested using the Borland C++ command line compiler version 5.5. However, a couple preparatory steps are necessary before building OOMMF with this compiler.

1. Properly complete bcc55 compiler installation.

   Be sure to read the `readme.txt` file in the `BCC55` subdirectory of the Borland install directory. In particular, check that the `bcc32.cfg` and `ilink32.cfg` configuration files exist in the `BIN` subdirectory, and have appropriate contents. If you omit this step you will get error messages during the OOMMF build process relating to the inability of the Borland compiler to find system header files and libraries. You will probably also need to add the Borland `BIN` directory to your `PATH` environment variable. Some of the Borland tools are fragile with respect to spaces in their pathnames, so you should either select the Borland install directory to be one without spaces anywhere in the pathname (e.g., use `C:`\`Borland`\`` instead of `"C:`\`Program Files`\`Borland`\`"`), or at least when setting the `PATH` use the ``8dot3'' style short name version of each component of the Borland install directory, e.g.,

       PATH=C:\Progra~1\Borland\BCC55\Bin;%PATH%

   Use ```dir /x`'' to display both the short and long versions of filenames. The Borland Developer Studio 2006 install automatically sets the path to include the long name version of the Borland `BIN` directory; you should manually change this via the System dialog box from the Control Panel. Select the Advanced tab, and pull up the Environment Variables sub-dialog. Edit the `Path` variable as discussed above; check both the ``User variables'' and the ``System variables'' settings. You will need to launch a new shell (command prompt) for the changes to take effect.

2. Create Borland compatible Tcl and Tk libraries.

   The import libraries distributed with Tcl/Tk, release 8.0.3 and later, are not compatible with the Borland C++ linker. However, the command line utility `coff2omf`, which is distributed with the Borland compiler, can be used to create suitable libraries from the Tcl/Tk .lib's. In the Tcl/Tk library directory (typically `C:`\`Tcl`\`lib` or `"C:`\`Program Files`\`Tcl`\`lib"`), issue the following commands

       coff2omf tcl84.lib tcl84bc.lib
       coff2omf  tk84.lib  tk84bc.lib

   Here `tcl84.lib` and `tk84.lib` are the input libraries (in COFF format) and `tcl84bc.lib` and `tk84bc.lib` are the new libraries (in OMF format).

   If `coff2omf` doesn't work, you can try creating the necessary import libraries directly from the Tcl/Tk DLL's. From the Tcl/Tk library directory issue the following commands:

       impdef -a tcl84bc.def ..\bin\tcl84.dll
       implib tcl84bc.lib tcl84bc.def

   This creates the Borland compatible import library `tcl84bc.lib`. Repeat with ``tk'' in place of ``tcl'' to create `tk84bc.lib`. The ``-a'' switch requests `impdef` to add a leading underscore to function names. This is sufficient for the DLL's shipped with Tcl/Tk 8.4, but other releases may require additional tweaking. The module definition file output by `impdef`, e.g., `tcl84bc.def` above, is a plain text file. You may need to edit this file to add or modify entries.

3. Edit `oommf`\`config`\`platforms`\`wintel.tcl`

   At a minimum, you will have to change the `program_compiler_c++` value to point to the Borland C++ compiler. The sample `wintel.tcl` file assumes the librarian `tlib` and the linker `ilink32` are in the execution path, and that the Borland compatible import libraries, with names as specified above, are in the Tcl/Tk library directory. If this is not the case then you will have to make appropriate modifications. Also, you may need to add the ``-o'' switch to the linker command to force ordinal usage of the Borland compatible Tcl/Tk libraries produced in the previous step.

After this, continue with the instructions in the Compiling and Linking section.

####
Using Digital Mars C++

To build using the Digital Mars C++ command line compiler (dmc), follow these instructions:

1. Install the Digital Mars C++ compiler, tools, and STL.

   Unpack the dmc archive into a convenient location. The default name for the root directory of the dmc installation area is ``dm''. Unpack the STLport (C++ Standard Library) into the dmc installation area. The top-level directory in the STLport archive is ``dm'', so if you unzip this archive from the parent directory to the dmc installation area it will naturally unpack into its standard location. Then modify the dmc configuration to include the STL header files. The `dm`\`bin`\`sc.ini` file should be edited so that the first element of the `INCLUDE` path is `"%@P%\..\stlport\stlport";`

   Next, use ```set INCLUDE`'' and ```set LIBRARY`'' from the DOS command prompt to check that these environment variables are either not set, or else set to values as needed by the Digital Mars compiler. (These variables names may be used by other applications, which will conflict with values expected by dmc.) To unset these variables, use the commands ```set INCLUDE=`'' and ```set LIBRARY=`''. For convenience, you probably also want to put the `dm`\`bin` directory into your environment `PATH` variable.

2. Create compatible Tcl/Tk import libraries.

   The Digital Mars linker uses the same library format as the Borland linker, and as in that case, you will have to build compatible import libraries for the Tcl/Tk libraries. The ``basic utilities'' package available from Digital Mars includes the `implib` import librarian that can be used for this purpose. Alternatively, you can use the Borland tools. See the section above on using Borland C++ for details.

3. Edit `oommf`\`config`\`platforms`\`wintel.tcl`.

   You will need to uncomment the entry for the dmc compiler, and comment out the other compiler selections. (The comment character is '#'.) The configuration file assumes that the dmc compiler and associated tools are in a directory included in your environment `PATH` variable.

After this, continue with the instructions in the Compiling and Linking section.

####
Setting the TCL_LIBRARY environment variable

If you encounter difficulties during OOMMF start up, you may need to set the environment variable TCL_LIBRARY. (NOTE: This is almost never necessary!)

Bring up the Control Panel (e.g., by selecting Settings|Control Panel off the Start menu), and select System. Go to the Environment tab, and enter TCL_LIBRARY as the Variable, and the name of the directory containing `init.tcl` for the Value, e.g.,

    %SystemDrive%\Program Files\Tcl\lib\tcl8.0

Click Set and OK to finish.

OOMMF Documentation Team
September 29, 2018