GSLWintel

GSLWintel
===========
Presented here is the GSL (GNU Scientific Library) compiled with Intel C/C++ on Windows
The GSL 1.15 was build with Visual Studio 2010 (VS), using Intel C/C++ 12.1 (Composer XE 2011 SP1).
The GSLWintel complete package contains one VS Solution (gslIntelSoln) and multiple VS Projects.
The GSL 1.15 source code has been placed in the appropriate directories. You can download the GSL source code and extract it to some other location for the purpose of comparing the source code with GSLWintel.
Upgradeble to GSL 1.16 and beyond - in order to do this, follow the build steps in "Building using Intel C/C++"
Absolute minimal changes to original GSL source code - all the hard work has been done in constructing the VS Solution and projects to consume the source code. To see the changes, see "Building using Intel C/C++" section.


Notation
=========
<gslsrc>     - the original gsl source tree
gslIntelSoln - the VS solution that holds this gsl build
gslIntel     - the name of the main gsl project under gslIntelSoln


What's different from between GSLWintel and Standard GSL on Linux
====================================================================
- this is build for Windows, 32bit or 64 bit.
- uses Intel C/C++ compilers
- for BLAS routines, the MKL library is used instead of the GSL cblas package. The reason is that since the Intel Compiler is being used already, the user should already have access to Intel's optimized blas library called MKL.
- <gslsrc>\cblas package is not included since MKL blas will be used.
- <gslsrc>\doc package is not included
- <gslsrc>\utils package is included but not compiled. Does not seem to have adverse affects
- to see what's missing or different from the original gsl source, you can always download the gsl source from the main GSL site, extract it to a different folder, and use it as a reference for comparison.


System Requirements
=====================
Visual Studio 2010
Intel C/C++ Compiler 12.1 with Intel MKL
Windows XP or later
GSL 1.15 source code


GSLWintel Structure
====================
- GSLWintel complete package contains one VS Solution called gslIntelSoln at the top level
- Under gslIntelSoln, there is VS project called gslIntel. This contains all the original gsl source code to be compiled into one GSL dynamic library called gslIntel.dll and gslIntel.lib.
- Under gslIntelSoln, there are also multiple VS test projects corresponding to each gsl package. For instance, gsl packages are block, complex, eigen, etc. Then there will be VS projects called test_block, test_complex, test_eigen.


Installation and Build
=========================
- The GSLWintel package is available on-demand. Please request it by posting a comment below.
- Extract the GSLWintel package and check (using Windows Explorer) that the structure is the same as described in the section above "GSLWintel Structure".
- Ensure Intel C/C++ compilers and Visual Studio 2010 are installed on your system.
- Open the solution gslIntelSoln.
- GSLWintel has been successfully build and tested for 32bit and 64bit.
  For 32bit choose Solution Configuration / Platform as: Debug / Win32
  For 64bit choose Solution Configuration / Platform as: ReleaseX64 / x64
- Simply Build the gslIntel VS project first.
- Then simply Build the other test_<package> VS projects. The test projects can be build one by one to see how it goes. Or highlight multiple test_<package> in Solution Explorer, then click Build Selection.
- Output is one gslIntel.lib, one gslIntel.dll. Also test_<package>.exe such as: test_block.exe, test_complex.exe
  For 32bit, gslIntel.* output is in   gslIntelSoln\Debug\
             test_<package>.exe are in gslIntelSoln\Debug\
  For 64bit, gslIntel.* output is in   gslIntelSoln\x64\ReleaseX64\
             test_<package>.exe are in gslIntelSoln\x64\ReleaseX64\
- GSLWintel is designed to be rebuilt easily by putting into the specific VS solutions and projects. But as always, unexpected errors will happen. In that case, you may need to debug yourself, but before doing that, read the section "Building using Intel C/C++" to gain an understanding of how GSLWintel was designed. Also see the Troubleshooting section.



Building using Intel C/C++
============================
Read this section if you want to understand how GWintel is put together.
The instructions in this section can be used to build your own GSL - Visual Studio 2010 Solutions and Projects.
This will be necessary if you wish build GSL 1.16 or any future versions.


This is based on the strategy used for "Building using Visual Studio C/C++"
Major structural change - using method from : http://gladman.plushost.co.uk/oldsite/computing/gnu_scientific_library.php

However, for the reasons below, we will not use gladman's template directly but instead use the same concept. The reasons are:
1. Using Gladman's VS2010 templates verbatim, may not work for the next version of GSL. It is better to build from scratch, documenting the steps, rather than using a black box.
2. Gladman's approach uses some processing of GSL source, and again, this may not work for future versions.
3. There is no guarantee of reduced effort if using Gladman's code, since a bug may take longer time to resolve.



Creating gsl project. For convenience, let:
<proj> = "gslIntel",
<gslSrc> = "src_1.15" = where original GSL source is extracted.


1. Prepare the following directory structure using Windows Explorer:
GSL_staging
    gslIntelSoln
    <proj>     (created by VS automatically)
<gslSrc>

Extract the raw / original GSL1.15 into <gslSrc>


2. Add new C++ project, with name <proj>.
Choose Location as ...../GSL_staging
Choose Solution name as gslIntelSoln
Choose "Create directory for solution"
Choose "Win32 project". Choose Application Type as "DLL", "Empty Project"

3. Convert to Intel C++ project. Right click on the project "gslIntel" in Solution Explorer.
Project -> Intel C++ Composer XE 2011 -> Use Intel C++

4. Go to the properties of <proj> and set the following properties:
Configuration Property
   C/C++
      General
    Suppress Startup Banner = NO     (this identifies which compiler is used).
//Additional Include Directory = $(ProjectDir)     ( this is for config.h)

5. Adding GSL source files. This section copies the GSL source files into the appropriate VS-project directories.
Manually Copy the files as shown below, note the name changes for some.
FROM GSL_staging/<gslSrc>                           TO  GSL_staging/gslIntelSoln/<proj>
   <package folder>/*.c                                  <package folder>/*.c
   <package folder>/*.h                                  <package folder>/*.h
   <package folder>/gsl_*.h                              gsl/gsl_*.h
   gsl_<package>.h                                       gsl/gsl_<package>.h
   config.h.in                                           config.h
   templates_on.h                                        templates_on.h
   templates_off.h                                       templates_off.h
   build.h                                               build.h

- Under GSL_staging/gslIntelSoln/<proj>, Solution Explorer has TWO VIEWS:
a. Show All Files ON
   This shows all subdirectories and all files, and most files are NOT included in the project to start with.
b. Show All Files OFF
   This shows the following FOUR folders, which will be filled automatically as files are Included into the project. The folders are:
   --- External Dependencies
   --- Header Files
   --- Resource Files
   --- Source Files
c. <package folder> can be block, err, matrix, etc....


d. To add the following packages into VS Projects, eg block, err, matrix, etc.....
- In Solution Explorer, choose Show All Files ON
- Go to each package sub-directory and add source files BY select "Include in Project". Include any other project as necessary, only include their *.c is OK. All header files do not need to be INCLUDED via Visual Studio because the C compiler will pull the contents of *.h hearder files in.
The general rules are:
----- Include *.c files mainly. Some included like *_source.c or *_inc.c or test_*.c and other test related files
      are also INCLUDED in Project, but EXCLUDED from Build.      
 Individual files can be excluded from Build (ie won't compile) by setting their properties individually.
      In Solution Explorer, choose Show All Files OFF. Go to "Source Files" directory to confirm package files are there.
 Also <package>\*.h files that do not begin with "gsl_".h, must also be included in the project.
----- Exclude <package>\gsl_*.h from project. These will be copied into the gsl sub-directory.

Build files. Assuming for Debug configuration, by default, *.obj files will be placed under:
      GSL_staging/gslIntelSoln/<proj>/Debug
By Default, *.dll will be placed in:
      GSL_staging/gslIntelSoln/Debug

WARNING: Some files, eg. file.c exist in multiple packages. The following step has to be done on file by file basis.
For most files which have unique names, ensure the compiled output is in:
- Project Properties - C/C++ - Output Files - Object File Name : $(IntDir)
For files like file.c with same name but in many packages, ensure that:
- Project Properties - C/C++ - Output Files - Object File Name : $(IntDir)<package>\
  where <package> is the name of the package
Example: since file.c is in packages histogram, matrix, etc, the property would be
  $(IntDir)histogram\
  $(IntDir)matrix\

To be complete, here is a list of *.c files that exist in multiple directories:
balance.c
beta.c
beta_inc.c
binomial.c
brent.c
bsimp.c
bspline.c
cauchy.c
chisq.c
combination.c
control.c
convergence.c
copy.c
cstd.c
deriv.c
diff.c
dwt.c
exppow.c
fdfsolver.c
fdist.c
fft.c
file.c
flat.c
fsolver.c
gamma.c
gauss.c
geometric.c
hyperg.c
init.c
inline.c
interp.c
laplace.c
linear.c
logistic.c
lognormal.c
matrix.c
minmax.c
multiset.c
nbinomial.c
newton.c
oper.c
pareto.c
pascal.c
poisson.c
prop.c
qr.c
qrng.c
rayleigh.c
reset.c
rk2.c
rk2imp.c
rk4.c
rk4imp.c
rk8pd.c
rkck.c
rkf45.c
rng.c
siman.c
sort.c
stat.c
step.c
swap.c
tdist.c
vector.c
view.c
weibull.c

*** source which are not compiled, eg *_source.c, *_inc.c, test* are ignored.



6. Edit the config file so that the "!" is removed in the following lines:
#if HAVE_DECL_LDEXP
#if HAVE_DECL_FREXP
#if HAVE_DECL_HYPOT
For some reason the use of preprocessor macros does not seem to work well. Hence the config.h file need to be modified as above.


7. In many matrix files, eg copy_source.c, file_source.c, getset_source.c, the copy.c, file.c, getset.c uses the templates_on/off.h which dynamically creates code using Preprocessor Macro definitions. This causes SEVERE problems at the line:
#define SHORT complex
because Microsoft Visual C redefines this in their math.h file as:
#define complex _complex
DO  NOT Put this macro definition /D__cplusplus  which may solve the _complex problem but creates new problems with other MS files like:

Error 1 error C2061: syntax error : identifier 'vc_attributes' c:\program files\microsoft visual studio 9.0\vc\include\codeanalysis\sourceannotations.h 42 VCPP_testDLL01

To solve the _complex problem definition, add this at the top of templates_on.h:
#ifdef complex
#define fixCOMPLEX_ 1
#undef complex
#endif

Also add this at the end of templates_off.h
// ASSUMES that the predefined complex is _complex in Microsoft's VC include\math.h and crt\src\math.h
#if fixCOMPLEX_ == 1
#define complex _complex
#undef fixCOMPLEX_
#endif

8. Right click on the GSLProj icon and select properties. In the Properties configuration, Configuration Properties:
- under C/C++ - Advanced
Calling Convention -  __cdecl (/Gd)
    Compile As         - Compile as C Code (/TC)
- under C/C++ - Preprocessor
    these should be automatically created here: WIN32, _DEBUG, _WINDOWS, _USRDLL, <Project>_EXPORTS
    manually added: GSL_DLL, DLL_EXPORT
- under C/C++ - Command Line
Add these compiler options: /DGSL_DLL /DDLL_EXPORT /DHAVE_VPRINTF=1
- under C/C++ - General - Additional Include Directories:
      enter the path to the current project folder.
- under Linker - General - Additional Library Directories:
      enter <fortranCompiler>\fortran\lib\ia32
- Go to the <proj> Properties - Configuration Properties - Intel Performance Libraries - Intel Math Kernel Libraries - Use MKL - Parallel
(The setup above enable the project to be linked to MKL's cblas routines.)



9. Removing cblas from GSL code.
- Exclude the cblas directory from the project
- Exclude the file gsl\gsl_cblas.h
- Remove the line
     #include <gsl/gsl_cblas.h>
  and replace if necessary with
     #include <mkl_cblas.h>
  for these files:
blas\blas.c
doc\examples\cblas.c    // probably not needed
eigen\francis.c
eigen\nonsymmv.c
gsl_blas_types.h

The rationale or excuse for not using GSL's cblas is that since we are building GSL with Intel C/C++ compilers, we should have license to the Intel MKL libraries too. Also Intel MKL should be highly optimised, thus hopefully more efficient.


10. Minimum  packages needed to compile DLL are:
block, complex, err, ieee-utils, matrix, sys, vector


11. Interoperability - Using DEF file method for exporting variables and functions.
- In the GSL project <proj>, right click and add new file.
- Choose the new file as a Module Definition file (*.def)
- In the contents of the file, type the following:
LIBRARY <proj>
EXPORTS
   funcA   @1
   funcB   @2
   funcC   @3
..... where funcA, funcB, funcC are the names of the functions to be exported. The ordinals @1, @2, @3 need to be consecutive numbers with no gaps in between. For functions exported in this manner, do not declare with __declspec(dllexport). It is possible to declare using both __declspec(dllexport)  and in DEF files, in this case, DATA or CONSTANT is used instead of ordinal numbers.
REF: MSDN Library - Importing and Exporting - Importing into an Application - Importing using DEF files.

- Ensure <proj> properties have the following Pre-Processors in addition to existing ones:
     WIN32, GSL_DLL, DLL_EXPORT
- go to gsl_ieee_utils.h and add the following near the top:
     #include <gsl/gsl_types.h>
- Ensure <proj> properties - Linker - Input - Module definition file : gslIntel.def
- Ensure the <consumer> project properties have the following Pre-Processors in addition to existing ones:
     WIN32, GSL_DLL    ....... do not have DLL_EXPORT
- Ensure the <consumer> project has these properties:
     Linker - Dependencies: gslIntel.dll
     Additional Library Directories: <location of gslIntel.lib>


12. Inline functions.
The following packages are affected: bspline, cdf
MSVC++ accepts both inline and _inline BUT when the code is *.c and compiled with MSVC, then it only recognize _inline.
Error Messages are like:
Error 1 error C2054: expected '(' to follow 'inline' ...\specfunc\cheb_eval_mode.c
Error 2 error C2085: 'cheb_eval_mode_e' : not in formal parameter list ...\specfunc\cheb_eval_mode.c
Error 3 error C2143: syntax error : missing ';' before '{' ...\specfunc\cheb_eval_mode.c 6
Solution:
In specfun/cheb_eval_mode.c, airy.c , gamma.c, bessel.c, bessel_olver, bessel_zero, coupling.c, ellint.c
erfc.c, legendre_con, trig.c, zeta.c
change from inline to _inline

***********************
  New INLINE Method
***********************
To AVOID changing any C code regarding "inline", creata a file "gsl/mygslIntel.h" and put this content into the file:
      #define inline _inline
Then put the following line
 #include <gsl/mygslIntel.h>
in the following files:
      config.h
 bspline/bspline.h
      gsl/gsl_sys.h
 gsl/gsl_sort.h
      gsl/gsl_heapsort.h
 gsl/gsl_rng.h
 interpolation/integ_eval.h

13. Excluded Source files.
As mention in a previous step, most *.c files within a package need to be "Include in Project". Then these types are generally excluded from BUILD:  *_inc.c, *_source.c and test*.c. However there are special cases where other *.c files also need to be EXCLUDED from BUILD - they are listed here.
cdf:      
eigen:       qrstep.c
fft:         exclude ALL files except - dft.c, fft.c, signals.c
histogram:   find.c, find2d.c, urand.c,
ieee-utils:  exclude ALL files except - endian.c, env.c, fp.c, make_rep.c, print.c, read.c, standardize.c
integration: append.c, cquad_const.c, err.c, initialise.c, positivity.c, ptsort.c, qpsrt.c, util.c,
             reset.c, qelg.c, qc25c.c, qc25f.c, qc25s.c, qpsrt2.c, set_initial.c,
linalg:      apply_givens.c, givens.c, svdstep.c
multifit:    lmiterate.c, lmpar.c, lmutil.c, lmset.c, qrsolv.c,
multimin:    directional_minimize.c, linear_minimize.c, linear_wrapper.c,
multiroots:  dogleg.c, enorm.c,
ode-initval2:control_utils.c, modnewton1.c, rksubs.c, step_utils.c
poly:        companion.c, balance.c, qr.c
rng:         schrage.c
specfun:     cheb_eval.c, cheb_eval_mode.c

To discover these *.c files to exclude, they are the ones usually included in other *.c.
So use a utility like BareGrep to scan all files for {#include "cheb_eval.c"} as an example. If that exist, then cheb_eval.c should be excluded from build compilation.


14. This section describes how to build the GSL-provided tests using VS2010 and the Intel C compiler.
The source file test.c is physically located at, eg:
      GSL_staging/gslIntelSoln/<proj>/sys/test.c
Creating Test projects for each package specifically:
- In the solution gslIntelSoln,  Add New Project - Visual C++ - Win32 - Win32 Console Application - "test_<gsl package>" -
  choose Console Application and Empty Project.
- Transform this to Intel C/C++ project by: right-click project - Intel C++ Composer XE 2011 - Use Intel C++
- In the test project, eg gslIntelSoln/test_block in Solution Explorer, right click on Source Files - Add Existing File.
- Choose the files to be tested by navigating to the gslIntelSoln/<proj>/block/ directory and select the test files such as test.c or others if applicable.
- Fill in for ALL CONFIGURATION, ALL PLATFORMS the following properties for the test project:
  C/C++ - General - Additional Include Directories - $(SolutionDir)gslIntel
  C/C++ - Preprocessor - WIN32, ...., GSL_DLL
  Linker - General - Additional Library Directories - $(OutputPath)
  Linker - Input - Additional Dependencies  - gslIntel.lib
- Compile and note the "error LNK2019" messages. If some variables or functons are not exposed, then edit the file
      gslIntel/gslIntel.def
  to add the functions and variables and recompile gslIntel and test projects.
- For the following test projects: test_eigen, test_linalg, test_wavelet, test_multifit, test_multimin,
  they use MKL and this can be configured by:
     - Project Propertie - Configuration Properties - Intel Performance Libraries - Intel Math Kernel Libraries - Use MKL - Parallel.
- For specfun test project, there is no test.c. Instead there are numerous test_sf* which must be included in test_specfun project.


15. Optimization
The following are various settings for the final version of the project, the gslIntel and all the test projects, hence usually apply to the Release configuration. These settings ensure the final product are not debug version, and also optimized by the compiler. In the project properties:

- under C/C++ - Preprocessor
    for test projects: WIN32, ....., _CONSOLE, GSL_DLL
    for gslIntel: WIN32, ....  GSL_DLL, DLL_EXPORT
ensure _DEBUG is not in any of them
- under C/C++ - Optimization
    Optimization: /O2, /Ox, etc..
    Enable Intrinsic Functions:   more testing needed about this option
- under C/C++ - Code Generation
Basic Runtime Check: Default
Runtime Library: Multi-threaded DLL  (Not Debug version)
- under C/C++ - Code Generation [Intel C++]
Intel Processor-Specific Optimization: more test needed
- under Linker - Debugging
      Generate Debug Info: No

Troubleshooting
=================
For crashes or compiling error first check the following:
- DO NOT / NEVER change any of the gsl source code such as *.c and *.h. In most cases Compile or Link failures is due to incorrect property settings in the VS solution gslIntelSoln or VS project settings gslIntel or other test_<package> project properties. There may be some different default settings in your VS compared to the VS settings used to build GSLWintel.
- Check preprocessor settings under Project Properties - C/C++ - Preprocessor
    for test projects: WIN32, ....., _CONSOLE, GSL_DLL
    for gslIntel: WIN32, ....  GSL_DLL, DLL_EXPORT
    The _CONSOLE ensures the test projects produce *.exe, while gslIntel must not have _CONSOLE because it needs to produce *.dll.
The DLL_EXPORT ensures the gsl variables in gslIntel.dll are visible to the outside world. The test projects are not export gsl variables hence must not have DLL_EXPORT.
- make sure MKL is used by specifying in:
    Project Properties - Configuration Properties - Intel Performance Libraries - Use MKL - PARALLEL option is on.


GSL-C-Fortran Framework
=========================
This section documents the projects and wrappers that need to be created to make use of gslIntel from Fortran projects.
The first part is to create a C-wrapper project (gslIntelCwrap) to create functions that will be called directly by other projects. These functions will make use of GSL functions internally. Hence gslIntelCwrap is a middle layer, used by other projects but internally calls GSL functions.
The second part is to write the appropriate interfaces for Fortran to call C functions.

1. At this stage there exist the GSL library with the following components:
gsl/gsl_xxxx.h      the header files
gslIntel.lib        - compile time library
gslIntel.dll        - runtime library

2. In VS2010, create a wrapper C++ project, say gslIntelCwrap. Create this as a C++ Win32 application, DLL, empty project (do not choose Export Symbols option).
3. Create a header file gslIntelCwrap.h and code file gslIntelCwrap.c
4. In the header file gslCwrap.h
a) prepare to export the wrappers.

extern "C"{
    __declspec(dllexport) void  mySinh(double x, double *result);
}

b) include reference to GSL header like and call gsl function:
#include "gslIntelCwrap.h"
#include "gsl/gsl_sys.h"
void mySinh (double x, double *result) {    
*result =  gsl_asinh(x);           // the actual gsl function
}// 2 * x;  }

5. Go to the gslIntelCwrap project properties page and fill the following:
- C/C++ - General - Additional Include Directories - <directory of gsl\gsl_xxx.h>
- Linker - General - Additional Library Directories - <location of gslIntel.lib>
- Linker - Input - Additional Dependencies - gslIntel.lib


6. To call from Fortran,
i) prepare a Fortran interface:
    interface
    SUBROUTINE fmySinh(x, dresult)  BIND(C, NAME='mySinh')
        USE, INTRINSIC :: ISO_C_BINDING     ! New Fortran 2003 standard
        IMPLICIT NONE
        REAL(C_DOUBLE), VALUE :: x
        REAL(C_DOUBLE) :: dresult
    END SUBROUTINE fmySinh
end interface

ii) In the Fortran code, just call the function as specified by the interface.
Eg.
    call fmySinh(1.2d0, answw)

iii) Add the following project properties before compilation.
- Linker - General - Additional Library Directories - <location of gslIntelCwrap.lib>
- Linker - Input - Additional Dependencies - gslIntelCwrap.lib   OR
  put the following line somewhere in the Fortran code:
             !dec$objcomment lib:'gslIntelCwrap.lib'

iv) Ensure the following dlls are in the path seen by the Fortran executable:
gslIntel.dll, gslIntelCwrap.dll


7. There are at least 3 projects involved here.
gslIntel - this keeps the gsl code in its own project, so that it is independent of any change in interface or usage.
gslIntelCwrap - this consist of the C wrappers so that it can be used by C code or Fortran code. It also transforms all gsl functions into VOID C functions so that it can be called as Fortran subroutines. Fortran Interface - this is freely linked to the gslIntelCwrap wrapper code. There is no direct reference to the GSL code.  

8. error LNK2019: unresolved external symbol
This error can occur with some of GSL functions which have not been exported.