In this tutorial, you will learn how to compile and build a MotionSolve user subroutine.
The user subroutine can be implemented as C/C++ or FORTRAN source code, C/C++ or FORTRAN
object files, or a combination of these.
For your convenience, MotionSolve contains a subroutine build
tool for Windows and Linux that can build the subroutine for
you. Using this subroutine requires no programming knowledge.
You can also build your user subroutine using an integrated development environment like
Microsoft® Visual Studio® on Windows. This is explained in this tutorial.
Table 1. Minimum Software Requirements to Compile and Build MotionSolve User Subroutine DLLs
Windows
Linux
Microsoft Visual Studio version 2005, both Express and Professional
GCC, version 4.1.2
Intel Visual FORTRAN Compiler 10
Use the MotionSolve Subroutine Build Tool to Create Shared
Libraries
The Altair Subroutine Builder is included in the MotionSolve installation for both Windows and Linux.
Follow these steps to build a MotionSolve-compatible
shared library using available source code.
Launch the build tool on Windows by clicking Start > Altair <version
number> > MotionSolve Subroutine
Builder
The MotionSolve Subroutine Builder dialog is
displayed:Figure 1.
To launch the build tool on Linux, navigate to
<altair_root>/altair/scripts/ and issue the
command:
./motionsolve_subroutine_builder
The GUI is displayed:Figure 2.
Specify Source Code or Object Files
The next step is to specify the source code or the object files that you will be
using to build the shared library. The following are valid source file types and can
be used to build a shared library:
C/C++ source code (*.c, *.cpp,
*.cxx)
FORTRAN source code (*.f,
*.f90)
FORTRAN or C/C++ object files (*.obj in Windows,
*.o in Linux)
A combination of the above.
Note: The remainder of this section
demonstrates using the build tool on Windows. The steps for using the
tool on Linux are identical.
Important: The source code or object files must all be located in
the same directory. You must have write-to-disk permissions for this
directory. If you do not have write-to-disk permissions for this
directory, please copy the source code to a location where you do have
write-to-disk permissions.
Also, if your source/object code is
located in different folders on your disk, please copy all
source/object code, along with any relevant files (like headers, for
example) to one common directory. Use this as your working directory
in the following steps.
To specify the source/object files, click next to the Source File(s)
field.
Figure 3.
Navigate to your working directory and choose the source files as required. You
can choose multiple files by holding down the CTRL button while clicking the
file names, or by clicking and dragging your mouse pointer.
Click Open to select these files.
Figure 4.
Specify the Output Directory
Next, you will specify the output directory where you would like the shared library
to be built. Again, you must have write-to-disk permissions for this directory.
Click Open next to the Output Name field.
Figure 5.
Navigate to the directory where you want the shared library to be built. Click
Select Folder to choose the current folder as the
output directory.
Before building the shared library, you need to specify a name for the shared
library. To do this, simply type in the name (without the extension) into the
Output Name field.
Note: The shared library name must contain only alphanumeric
characters (A-Z, a-z, 0-9) with the exception of the underscore ("_")
character.
Figure 6.
Build the Shared Library
To build your shared library, click Build.
Figure 7.
For the Windows platform, if you have multiple compilers installed on your
computer, you can choose which compiler to use while building your shared
library.
Figure 8.
Upon building the source files successfully, the following dialog is
displayed:Figure 9.
Additionally, you will see the shared library built by the tool in your
working directory (C:\Test in this case). You can use
this library in a MotionSolve
simulation.
The tool also creates a temporary directory inside your
working directory while building the shared library. The contents of this
temporary directory can be used for debugging and informational
purposes.
Note: The temporary directory created inside of
your working directory contains some useful information:
build.bat: a batch file that contains the
compiler and linker commands used to build the shared library.
build_output.log: a log file that contains
messages from the compiler and linker. The contents of this file are
useful when debugging an unsuccessful build.
For a successful
build, this directory also contains compiled objects, the linked
library and other temporary files. If you specified only C/C++
source files and/or object files, the tool also creates a
Microsoft® Visual Studio® solution file in this
directory.
If, however, your build is unsuccessful, the following dialog is
displayed: Figure 10.
To investigate the cause of build failure, look at the
build_output.log file at the location stated in the
dialog above. This file typically contains compiler/link time errors or warnings
that may help you debug your source code.
After you have finished using the tool, you can exit by clicking
Quit. If you built a shared library before quitting,
you are given the option to remove the temporary folder created by the
tool.
Frequently Asked Questions
Can the tool build a shared library when both Fortran and C/C++ source code is specified?
Yes, the tool can handle mixed source code as well as object files.
What platform does the tool build my library for?
The supported platforms are 64-bit Windows and 64-bit Linux.
Is my shared library a debug or release version?
The shared library created is a release version library.
Where can I get sample templates for the syntax of the
C/C++/Fortran code?
Sample user subroutine code is provided in the installation in the following
locations:
For C/C++ source code:
<install>\Altair\<version>\hwsolvers\motionsolve\usersub\c_src
For Fortran source code:
<install>\Altair\<version>\hwsolvers\motionsolve\usersub\f_src
Note: For MotionSolve to use the
functions defined in the source code, these functions must be exported on the
Windows platform (on Linux, all functions are
automatically exported). The syntax to do this for C/C++ and Fortran is described below.
C/C++
Include the header file msolvsub_c_include.h
(located in
<install>\Altair\<version>\hwsolvers\motionsolve\usersub\c_src\include)
in your code. To export a function, use the keywords
CLINKAGE, DLLFUNC, and
STDCALL.
#include " msolvsub_c_include.h"
#include "stdlib.h"
CLINKAGE DLLFUNC
void
STDCALL
ARYSUB (int *id, double *time, double *par,int *npar, int *dflag, int *iflag, int *nvalue, double *value)
{
}
Fortran
In Fortran syntax, the same function
above can be exported as shown
below:
Does the order in which I choose the source files
matter?
Yes, this can matter in certain cases. For example, when building Fortran source code and defining MODULES, you may want to
include the source file that contains the definition of any defined modules before
the source files that refer to these modules.
I am not able to compile Fortran
files even though I have a supported Intel Fortran
compiler installed. What's wrong?
The build tool relies on an environment variable to detect the version of the Intel
Fortran compiler and its location on your machine.
Make sure you have the environment variable IFORT_COMPILERxx (where xx is the
version of the compiler - 10, 11 or 12) defined correctly on your system and
pointing to the installed version.
Use the Microsoft® Developer Studio to Build a Shared Library
To successfully build a shared library using the steps below, you will need to have
write-to-disk permissions for your installation directory.
Building a C++ User Subroutine DLL using Microsoft® Visual Studio®
To successfully build a shared library using the steps below, you will need to have
write-to-disk permissions for your installation directory.
Open Microsoft Visual Studio 2005 (Express and Professional Editions will
work).
From the File menu, select Open > Project/Solution.
Browse to
<install>\Altair\<version>\hwsolvers\motionsolve\usersub\c_project,
select the file ms_csubdll.vcproj and click
Open.
Note: If you are using a version newer than Visual Studio 2005, you
will be prompted to convert the project file. Please proceed with the
default options for the conversion. Once converted, the new project file is
loaded to your workspace.
In the Solution Explorer, the CPP subroutines that are part of the
solution are listed.
Double-click any of the CPP files that you want to modify/view and make the
required changes.
Click Save to save the changes made to the file.
Choose the configuration for your shared library.
Figure 11.
Make sure that the target type for the shared library matches your
installation. For example, choose x64 for a 64-bit
installation of the application.
Select Build > Build Solution to build the DLL. You will be prompted to save the solution. Save
the solution in a directory of your choice.
After successfully completing the build, Visual Studio displays a
message as shown below:Figure 12. The DLL ms_csubdll.dll is located in
<install>\Altair\<version>\hwsolvers\motionsolve\usersub\c_project\<platform>\<config>\ms_csubdll.dll.
Building a FORTRAN User Subroutine DLL using Microsoft® Visual Studio®
The same steps can be repeated to build a FORTRAN user subroutine DLL for MotionSolve. The only difference is that the Visual Studio
project file to be opened is ms_fsubdll.vfproj. All the other
steps remain the same.