Inline::F2003 Files

README v1.03 - 14 FEB 2021

  INTRODUCTION
    This project features the Perl program matopmul.pl to showcase the Perl
    module Inline::F2003. This module enables interoperability between Perl
    and modern Fortran. It reads the inlined Fortran source, compiles it
    with the chosen Fortran compiler and builds the executable shared
    library. After installing and loading the newly built library, the
    program calls the inlined Fortran subroutine like a Perl function. The
    resulting output is a matrix that was calculated and displayed by
    Fortran code.

  PROJECT URL
    <https://sourceforge.net/projects/inline-f2003/>

  AUTHOR
    Ron Grünwald <rongrw@users.sourceforge.net>

  ACKNOWLEDGEMENTS
    Ingy döt Net <ingy@cpan.org> - Author of Inline and Inline::C

    Inline-Perl <inline@perl.org> - Discussion forum for Inline and ILSMs

  COPYRIGHT
    Copyright 2017-2021. Ron Grünwald.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See <http://www.perl.com/perl/misc/Artistic.html>

  PREREQUISITES
    The module Inline::F2003 is an Inline Language Support Module (ILSM),
    and therefore requires the "Inline" Perl module for its operation. The
    following requirements must be met before "matopmul" can be executed.

            Perl 5.12 or higher
            Perl module "Inline" installed
            Perl module "Inline::C" installed
            Perl module "Regexp::Common" installed
            Fortran compiler installed that is compatible with the 2003 standard

  LIMITATIONS
    This release of "matopmul" was developed and tested on Fedora Linux.
    However, my intention is for the software to execute under different
    operating systems using a range of different Fortran compilers.

    If your system is not Linux-based, you are still encouraged to run
    "matopmul". The program will most likely fail, but I would really
    appreciate if you could report the failure back to me by sending an
    e-mail, or submitting a ticket through the project website on
    SourceForge. See PROJECT URL above.

  PACKAGE CONTENTS
    The software distribution contains the following files:

            matopmul/1.03/README.html
            matopmul/1.03/README.pod
            matopmul/1.03/CHANGES
            matopmul/1.03/lib/perl5/Inline/F2003.pm
            matopmul/1.03/lib/perl5/5.20/Inline/F2003.pm
            matopmul/1.03/matopmul.pl
            matopmul/1.03/matopmul.mk
            matopmul/1.03/matopmul.c
            matopmul/1.03/CheckInlineDir.pl
            matopmul/1.03/ModMatrixOps.f03

  UNPACKING
    1. Choose/create an installation directory with read-write access (eg.
    your home dir.)
    2. Change into the installation directory
    3. Move the downloaded tar-file into this directory
    4. Run the command: "tar zxvf matopmul-1.03.tar.gz"
    5. The contents are unpacked into the directory "matopmul/1.03"

  EXECUTING
    After unpacking the tar-file, you may execute the program using the
    following commands:

            cd matopmul/1.03
            perl matopmul.pl

    This will display several lines of output. The final set of lines should
    read

            Matrix of Scalar Products:
        
               |  5.760   5.760   0.000  |
               |  5.760  20.200  14.440  |
               |  0.000  14.440  14.440  |

    The resultant matrix is calculated and displayed by the compiled Fortran
    2003 source. It indicates that the program has executed correctly on
    your platform.

    The program matopmul.pl is configured to use the GNU Fortran compiler
    (gfortran) by default. If you wish to use a different compiler, you need
    to edit matopmul.pl. Locate the hash array %FortranOpts in the
    Inline::F2003 Configuration Section. Change the values for the keynames
    "BIN" and "VND" to match your compiler.

    For example, if you intend to use the PGI Fortran compiler, change the
    values to

            BIN => "pgfortran"
            VND => "PGI"

  RUNTIME ENVIRONMENT
   Two Flavours of the Inline::F2003 Module
    The "matopmul" distribution contains two variants of the Inline::F2003
    module. The first variation, referred to as the "compatible" module, can
    execute with Perl v5.12 or higher. The second variation, referred to as
    the "modern" module, can only execute with Perl v5.24 or higher. It
    utilises Perl features that were first introduced in v5.20. The program
    matopmul.pl will automatically load the appropriate variation of
    Inline::F2003, depending on the version of Perl that is executing.

   The Build Directory of Inline::F2003
    The default behaviour of the Inline module is to create a root directory
    named "_Inline", below which all the build and install files and
    directories are created. A more meaningful name for the Inline root
    directory can be specified with the "DIRECTORY" option. The "matopmul"
    distribution contains the file CheckInlineDir.pl, which generates a
    directory name based on OS and machine architecture. An example would be
    "inl-linux-x86_64". If the directory name does not exist in the current
    directory, it will be created.

  THE F2003 MODULE
   NAME
    Inline::F2003 - Perl language interface module for Fortran 2003 and
    higher

   VERSION
    This document describes Inline::F2003 version 0.9902

   PREREQUISITES
    The following Perl modules must be installed

            Inline
            Inline::C
            Regexp::Common

   DESCRIPTION
    Inline::F2003 is a Perl extension module that allows program units
    written in modern Fortran to be added into the __DATA__ section of a
    Perl program. The term "program units" is a collective Fortran term that
    refers to subroutines, functions, and module procedures. The module
    reads the Fortran source, compiles it into object files and builds the
    shared library file.

    Inline::F2003 is dependent on the "Inline" Perl extension module. It is
    referred to as an ILSM (Inline Language Support Module). Inline performs
    many functions, including loading the shared library that was built and
    installed by the ILSM. Inline::F2003 operates differently to other ILSMs
    in that regard. The shared library that it builds must be loaded through
    Inline::C rather than Inline. This is discussed in more depth in the
    section "USING THE MODULE".

    The Fortran source written by the programmer must utilise the C
    interoperability features of the Fortran 2003 standard and higher. The
    reason for this is that the Fortran program units must be callable from
    C, since the C language constitutes Perl's native interface. The chosen
    compiler must therefore be compatible with Fortran 2003. Older compilers
    that can only interpret Fortran77 or Fortran90 will definitely fail.

    The Fortran compilers that have been tested and are supported are

            GNU Fortran - open source
            G95 Fortran - open source, no longer maintained
            NAG Fortran - commercial
            PGI Fortran - commercial and free community edition

   USING THE MODULE
    Inline::F2003 is always loaded and executed by its parent module,
    Inline. This usually occurs at compile-time. The source code fragment
    below illustrates the typical way to load and execute Inline::F2003.

      use File::Spec;

      use Inline F2003 => "DATA",
               ( FOR       => "gfortran",
                 MAKEFILE  => "matopmul.mk",
                 MAKEDIR   => File::Spec->curdir(),
                 SRCLIST   => [ qw( ModMatrixOps.f03 ) ],
                 DIRECTORY => $main::InlineRoot );

    The first line of the "use Inline ..." statement loads the Inline module
    at compile-time. Inline then loads the Inline::F2003 module and is
    instructed that the Fortran source to be compiled is found in the
    "__DATA__" section of the Perl program.

    The remaining lines specify various configuration options as a list of
    key/value pairs. The DIRECTORY option, shown last, is not actually an
    Inline::F2003 option. Instead, it belongs to Inline. The configuration
    options that are specific to Inline::F2003 are documented in the section
    "CONFIGURATION OPTIONS".

    When the code fragment above has finished executing, Inline::F2003 would
    have built a shared library from the Fortran source. Normally Inline
    loads the shared library, but with Inline::F2003 the shared library must
    be loaded by Inline::C. This is best performed at run-time. The
    appropriate way to load Inline::C at run-time, specifying the Fortran
    shared library, is shown below.

      use constant { BOOL_T => 1, BOOL_F => 0 };

      Inline->bind( C => "./matopmul.c"
               => ( MYEXTLIB    => Inline::F2003->getlib(), 
                    FORCE_BUILD => Inline::F2003->newlib(), 
                    DIRECTORY   => $main::InlineRoot,
                    PRINT_INFO  => BOOL_T ));

    The first line of the "Inline->bind( ..." statement instructs Inline to
    load Inline::C, and to access the C source in the external file
    matopmul.c. The next line uses the MYEXTLIB option to specify the name
    and path of the Fortran shared library. The line following it reads a
    flag value that was set by Inline::F2003. This flag instructs Inline::C,
    through the FORCE_BUILD option, whether or not to build a new C shared
    library.

    The above Inline::C source fragment is the crucial piece that enables
    interoperability between Perl and Fortran.

   CONFIGURATION OPTIONS
    The configuration options for an ILSM are specified as a list of
    key/value pairs. Inline::F2003 currently provides five configuration
    options, described below.

   FOR => "value"
    This configuration option specifies the Fortran compiler to use. It must
    always be provided, otherwise Inline::F2003 will terminate. The value
    may be specified either as the executable name or the full path and
    filename of the compiler.

    The following examples illustrate valid use of this option

            FOR => "gfortran"
            FOR => "/usr/local/bin/g95"

   MAKEFILE => "value"
    This configuration option specifies the name of the makefile. If this
    option is not provided, Inline::F2003 will assume the value of
    "Makefile". Pathnames are not permitted in the value of this option.

   MAKEDIR => "value"
    This configuration option specifies the pathname of the makefile.
    Absolute or relative pathnames are permitted. If this option is not
    provided, Inline::F2003 will assume the value of the current directory.

    During the validation process, Inline::F2003 combines the values for
    MAKEDIR and MAKEFILE to ensure that the specified makefile exists.

   SRCLIST => [ list-value ]
    This configuration option specifies a list of external Fortran source
    files to be included in the build process. At present the value of this
    option can only be specified as an array reference. The list of external
    source files must reside in the same directory as the makefile.

    Inline::F2003 checks that each external file exists. If a file in the
    list is not found, the module will terminate.

   BUILD_LIB => bool-value
    This configuration option accepts a boolean value to indicate whether
    the module should compile and build a shared library. If this option is
    not specified, Inline::F2003 will assume the value TRUE and build the
    shared library. This option is intended mainly for unit testing.

   PUBLIC ACCESSOR METHODS
    Inline::F2003 provides a set of accessor methods that are intended to be
    called outside the module. These accessor methods should only be called
    after the module has loaded and compiled the inlined Fortran source.

   Inline::F2003->getlib()
    The getlib() accessor method returns the full path and filename of the
    installed shared library that was built by Inline::F2003.

   Inline::F2003->newlib()
    The newlib() accessor method returns a flag value indicating whether or
    not a new shared library was built by Inline::F2003.

   Inline::F2003->ilsm()
    The ilsm() accessor method returns a reference to a copy of the internal
    hash data structure created by Inline::F2003. This method is intended
    mainly for unit testing.

   End of Document