                Release Notes for MEX-Files for Matlab 4.2
                ------------------------------------------

    Table of Contents
    -----------------

        1. Customizing mex
        2. .mexrc.sh file
        3. CASE=value command line option for difficult cases
        4. Examples
           4.1 Sun4
               4.1.1 SunOS4.1.1 linker bug - can't use -r with -Bstatic
           4.2 Sol2
               4.2.1 Using 'standard' Sun compilers
        5. SunOS 4.1.3 linker (ld) bug - undefined symbols
        6. Building IRIX 4.x MEX-Files on IRIX 5.0
        7. Problems



    1. Customizing mex

       The MathWorks makes a best effort to try to configure the cmex and
       fmex scripts with default values for system configuration variables 
       that work for the majority of our customers. However, if the values
       of these variables do not work for your environment then customizing
       will be necessary. 

       The basic strategy is to configure a template file called .mexrc.sh
       found in the matlab/bin directory for global MATLAB use. If a user
       needs further customization then this global file should be copied
       to the user's home directory and further modified. As a final step
       variables can be passed as arguments to cmex or fmex in the form:

                        name=definition

       Definitions which have white space must be placed in single quotes
       (').

       The .mexrc.sh used is the first occurrence of this file in the
       directory list:

                        .               (current)
                        $HOME           (home)
                        matlab/bin      (default location)

       Nothing is sourced if this file cannot be found. If you use the
       -v option with cmex or fmex it will tell you which file is sourced.

       Which value does a variable take? If you provide a value for
       one of the following variables in .mexrc.sh

                MATLAB                  (MATLAB root directory)
                CC                      (C compiler)
                CFLAGS                  (C compiler options)
                FC                      (Fortran 77 compiler)
                FFLAGS                  (Fortran 77 options)
                FCLIBS                  (minimum required libraries for FC)
                LD_CCLIBS               (C standard libraries for ld(1))
                LD_FCLIBS               (Fortran 77 standard libraries for
                                        ld(1))

       then it will supersede the default value in cmex or fmex. You can
       add other variable assignments to .mexrc.sh to affect the local
       environment of the executing cmex or fmex script. A variable passed
       as an argument ALWAYS supersedes any other variable assignement.
       
       IMPORTANT: 1. Run cmex or fmex WITHOUT arguments to see the default
                     values set in each script for the variables listed
                     above.
                  2. Run cmex or fmex with the -v option to see the final
                     values for the variables listed above (and more) after
                     all default values, .mexrc.sh file values, and
                     argument values are considered.
       
    2. .mexrc.sh file

       This is a Bourne Shell script that is sourced by cmex and fmex.
       It is basically a switch that branches on the value of the machine
       architecture (Arch) and executes a set of variable assignment
       statements which by default all have a value of null.

       The variables listed are:

               MATLAB                  (MATLAB root directory)
               CC                      (C compiler)
               CFLAGS                  (C compiler options)
               FC                      (Fortran 77 compiler)
               FFLAGS                  (Fortran 77 options)
               FCLIBS                  (minimum required libraries for FC)
               LD_CCLIBS               (C standard libraries for ld(1))
               LD_FCLIBS               (Fortran 77 standard libraries for
                                        ld(1))

       If you want to find out the default values for those variables
       execute the cmex -v or fmex -v. If those defaults do not work then
       you will need to provide values by filling in the right hand side of
       the assignment statements for those variables. Remember no spaces
       around the '=' in the variable assignment. Values which have white
       space require single quotes (').

       There is a section at the end of this file where these variables can
       be set and made to apply to all architectures. You must remove the
       comment character '#' before they can have effect. Remember that they
       supersede any architecture specific value for that variable.

       You have complete freedom to add other assignment statements and code
       that has a bearing on the compilation and linking of your MEX-files.
       
       We now give a concise discussion of the variables listed above.
       The following variables are supported for user modification.

       MATLAB           (MATLAB root directory)

                        Default is determined at run time by cmex or fmex
                        as the parent directory of the directory where the
                        script is.

                        If the MATLAB directory is in an automounted file
                        system you may want to set this to the correct
                        mountable path rather than use the full mounted
                        path determined by the script.

       CC               (C compiler)

                        Default is first 'cc' command on your path.

                        For example, if your C compiler is gcc set CC='gcc'.

       CFLAGS           (C compiler options)

                        Default is platform dependent. See the output of
                        cmex -v or fmex -v.

                        Consult you compiler man page or documentation
                        for appropriate options.

       FC               (Fortran 77 compiler)

                        Default is first 'f77' command on your path.

                        For example, if your Fortran compiler is FORT
                        set FC='FORT'.
                        
       FFLAGS           (Fortran 77 options)

                        Default is platform dependent. See the output of
                        cmex -v or fmex -v.

                        Consult you compiler man page or documentation
                        for appropriate options.

       FCLIBS           (minimum required libraries for FC)

                        Default is platform dependent. See the output of
                        cmex -v or fmex -v.

                        This is the minimum libraries needed for the
                        following to work:
                                fmex -debug yprime.f yprimeg.f

       LD_CCLIBS        (C standard libraries for ld(1))

                        Default is platform dependent. See the output of
                        cmex -v or fmex -v.

                        This can be tricky. This is VERY platform dependent!

                        The standard libm and libc libraries in the
                        appropriate format are commonly required. The
                        default value rarely has to change.

                        NOTE: (sun4 only)

                              No dummy assignment is provided in the
                              standard .mexrc.sh file becasue you should not
                              need to use it. The correct list is generated
                              by a dry run of the C compiler in the cmex
                              script. Use cmex in verbose mode, -v, to see
                              what libraries are actually being linked in.

       LD_FCLIBS        (Fortran 77 standard libraries for ld(1))

                        Default is platform dependent. See the output of
                        cmex -v or fmex -v.

                        This can be tricky. This is VERY platform dependent!

                        NOTE: (sun4 only)

                              No dummy assignment is provided in the
                              standard .mexrc.sh file because you should not
                              need to use it. The correct list is generated
                              by a dry run of the Fortran compiler
                              in the cmex/fmex scripts. Use cmex/fmex in
                              verbose mode, -v, to see what libraries are
                              actually being linked in.

    3. CASE=value command line option for difficult cases

       Since the combinations of compilers and loaders with and without
       bugs is almost endless on platforms like the sun4 an additional
       capability to be used in conjunction with the .mexrc.sh file is
       provided to help you with those difficult cases.

       You may require this capability on networks where machines are at
       different levels of the OS and are at various patch levels. Of
       course you could structure your .mexrc.sh to check for specific
       hostnames, for example, so this technique does not have to be used.
       Remember, arbitrarily complex Bourne Shell code can be used in
       the .mexrc.sh file.
       
       It also is used to workaround bugs in system software. See Example
       4.1.1. In this example, we use LIBS both in cmex and fmex, but they
       are different depending whether you need Fortran or C. The command
       line option is used to select which LIBS variable to use.

       The system works as follows:

       1. Supply an option to cmex or fmex of the form:

          CASE=value

          where value is a string without quotes and whitespace.  The
          keyword CASE must be in uppercase.
       
       2. Structure your .mexrc.sh around a case or if-then-else
          statement that uses the value of CASE to select which branch.

       As a demonstration, here is a sun4 fragment for .mexrc.sh to replace
       the one in the standard file. There are three cases, 411, 413, and
       everything else. You should always provide a '*' case (the default)
       so that if you do not provide a CASE option or use a value different
       then the listed cases something is executed.

=============================================================================
        sun4)
#----------------------------------------------------------------------------
# LD_FCLIBS and LD_CCLIBS are not explicitly listed because a dry run of
# the appropriate compiler is done in the cmex/fmex scripts to generate
# the correct library list. Use -v option to see what libraries are actually
# being linked in.
#----------------------------------------------------------------------------
# cmex & fmex
            case "$CASE" in
                411)
                   MATLAB=
                   CC=
                   CFLAGS=
                   FC=
                   FFLAGS=
                   ;;
                413) 
                   MATLAB=
                   CC=
                   CFLAGS=
                   FC=
                   FFLAGS=
                   ;;
                *)
                   MATLAB=
                   CC=
                   CFLAGS=
                   FC=
                   FFLAGS=
                   ;;
            esac
#----------------------------------------------------------------------------
            ;;
=============================================================================

       So if your wanted to compile say yprime.c on a sun4 which is covered
       by case '411' you would say:

           % cmex CASE=411 yprime.c

    4. Examples

       4.1 Sun4

           4.1.1 SunOS4.1.1 linker bug - cannot use -r with -Bstatic

                 If you try cmex/fmex using the standard .mexrc.sh file
                 and you get a linker message saying that you

                 '. . . cannot mix -r with -Bstatic flags . . .'

                 then the CASE capability mentioned in section 3. above
                 can be used to solve this problem.

                 A possible replacement sun4 code fragment for the .mexrc.sh
                 file is given below. Read it carefully and make any changes
                 that are appropriate to your system.

                 WATCH OUT! The quotes around the right hand side for LIBS
                            MUST be single quotes to postponed evaluation 
                            until later!
                 
=============================================================================
        sun4)
            MATLAB=
            CC=
            CFLAGS=
#
# We assume that the f77 command which is the default refers to $FDIR/f77
# See FDIR defined below
#
            FC=
            FFLAGS=
#
# FDIR = directory where the Fortran compiles is stored. Yours may not
#        be precisely SC0.0. So replace it.
#
            FDIR=/usr/lang/SC0.0
#
            case "$CASE" in
                f)
                    LIBS='$MATLAB/extern/lib/sun4/libmex.a \
                          $FDIR/libF77.a $FDIR/libm.a /usr/lib/libc.a'
                    ;;
                c)
                    LIBS='$MATLAB/extern/lib/sun4/libmex.a \
                          /usr/lib/libm.a /usr/lib/libc.a'
                    ;;
                *)
                    LIBS='$MATLAB/extern/lib/sun4/libmex.a \
                          /usr/lib/libm.a /usr/lib/libc.a'
                    ;;
            esac
            ;;
=============================================================================
         
                 If you compiling Fortran files with fmex then use:

                     % fmex CASE=f . . .

                 If you compiling C files with cmex then use:

                     % cmex CASE=c . . .

       4.2 Sol2

           4.2.1 Using 'standard' Sun compilers

                 All compilers on Solaris 2.X are unbundled products. The
                 cmex/fmex variable defaults are set up assuming Sun
                 Compilers and a compile environment set up according
                 to the compiler documentation.

                 If you want to encapsulate this environment in your
                 .mexrc.sh here is a fragment to start with.

                 Here we have assumed the 'standard' location of the
                 compilers as '/opt/SUNWspro' and the version as 'SC2.0.1'.
                 
                 WATCH OUT! The quotes used around some of the right hand
                            sides MUST be single quotes to postpone
                            evaluation until later!

=============================================================================
        sol2)
#----------------------------------------------------------------------------
# cmex & fmex
            MATLAB=
            CC='/opt/SUNWspro/SC2.0.1/cc -G'
            CFLAGS=
            FC=/opt/SUNWspro/SC2.0.1/f77
            FFLAGS=
            LD_FCLIBS=
# cmex only
            LD_CCLIBS=
#----------------------------------------------------------------------------
            ;;
=============================================================================

    5. SunOS 4.1.3 linker (ld) bug - undefined symbols

       With SunOS 4.1.3 a new linker (version 1.144) was introduced which
       supposedly fixed all known problems with earlier loaders.

       UNFORTUNATELY, they introduced a bug with the -r option which caused
       ld to fail to pick up symbols from archive libraries. The -r option
       is used by cmex and fmex. The MEX-file generally compiles with no
       errors but fails to load with one or more messages of the form:

           Undefined symbol '. . .' in file . . .
           . . .
           ??? Invalid MEX-file

       An earlier workaround was to repeat the libraries two or more times.
       This is HIGHLY inconvenient!

       To find out what version of the linker you have execute the command:

            % strings /bin/ld | grep 'ld\.c'

       The correct linker is:

            @(#)ld.c 1.145 92/12/13

       fix: Get version of 1.145 of the linker. This is available as
            Sun patch 100170-10. For MathWorks customers the compressed
            tar file of this patch is available on our anonymous FTP server
            (ftp.mathworks.com) as:

                ./pub/tech-support/patch/sun4/sun.ld.1.145.tar.Z

            See the README file in the patch directory for installation
            instructions.

       WATCH OUT! If you are using this patch with SunOS 4.1.1 you will
                  need an additional patch for libc which is NOT available
                  from The MathWorks.

    6. Building IRIX 4.x MEX-Files on IRIX 5.0

       In the .mexrc.sh file, add the following lines under sgi:

           osversion=`uname -r`
           if [ "`expr $osversion : '5.*'`" != "0" ]; then
               if [ "$SGI_IRIX4" = "" ]; then
                   SGI_IRIX4=/usr/irix4; export SGI_IRIX4
               fi
               LD_CCLIBS="-L$SGI_IRIX4/usr/lib -lm -lc"Õ
               LD_FCLIBS="-L$SGI_IRIX4/usr/lib -lF77 -lI77 -lU77 -lisam -lm -lc"
           fi

       Change the value of SGI_IRIX4 if that is not correct for your system.

       NOTE: The format of all libraries must be in COFF. You cannot
             build MEX-files that reference IRIX 5.0 libraries
             that have no COFF equivalents.



    7. Problems

       If you have questions or want to report problems please contact:

           The MathWorks, Inc. Technical Support:

           Phone: 508-653-1415
           FAX:   508-653-2997
           Email: support@mathworks.com

-------------------------------------------------------------------------------
Copyright (c) 1992-94 by The MathWorks, Inc.
$Revision: 1.10 $  $Date: 1994/10/07 21:15:37 $
-------------------------------------------------------------------------------
