File	Date	Author	Commit
config	2013-09-19	Ricardo Fabbri	[ada153] simpletoolbox works on scilab master branch as ...
src	2013-09-19	Ricardo Fabbri	[ada153] simpletoolbox works on scilab master branch as ...
COPYING.txt	2005-07-18	Angus Errington	[a4bedb] Initial Import
ChangeLog.txt	2005-07-23	Zhang Cheng	[7d766e] no message
Makefile.am	2013-09-19	Ricardo Fabbri	[4fc1c5] minor changes to makefile
README.txt	2005-07-18	Ricardo Fabbri	[d71742] changed email address
autogen.sh	2013-09-19	Ricardo Fabbri	[1eb64f] updated autogen to match SIP
configure.ac	2013-09-19	Ricardo Fabbri	[7f7d22] compiles.

Read Me

This is a simple package to show how the GNU Autotools may be used
to build a Scilab toolbox. Although this is a simple example, this
framework is very robust and flexible, allowing you to:

   o  Add tests for external libraries and system routines

   o  Make very portable toolboxes: they will work with almost all
      Unix flavours, including MinGW and Cygwin under Windows

   o  Make your toolbox work with different versions of Scilab,
      both installed from source and from binaries

   o  Have total control over the build process

This and other advantages enables the programmer to build complex
toolboxes in a robust easy-to-install way.


INSTALLATION
============

UNIX
----

$ configure 

This will configure the toolbox to be installed at SCI/contrib/simple.
To install in another directory, say $HOME/temp: 

$ mkdir $HOME/temp
$ configure --prefix=$HOME/temp

To compile and install the toolbox:

$ make
$ make install

Now enter inside scilab and execute the "loader.sce" script placed in 
the directory where the toolbox was installed. There will be silly a 
routine called "soma" that returns the sum of its two arguments. Of 
course, the autoconf/automake setup is suited for complex projects, 
not simple ones, but this is just an example.


MINGW BUILD
-----------

MinGW (Minimallist GNU for Windows) is a set of development tools for 
generating native Windows code. It enables you to compile this toolbox 
using configure and make, similar to Unix. 

There are some specific things that you must set up by hand in 
order to compile this toolbox with MinGW. The whole process consists 
in the following steps

1) Vist www.mingw.org, download and install the following packages:
   MinGW, MSYS, and MSYS-DTK

2) Your scilab installation must be in c:\scilab (/c/scilab in MSYS), 
   because this path is hardcoded in the build process.  Please move 
   your scilab installation to that place or else put an entry in the 
   /etc/fstab file inside MSYS.  You can also alter the SCIDIR 
   variable in the configure.ac file but this was not tested. 

3) Inside /c/scilab/bin (MSYS path), we must rename the libraries 
   "LibScilab.*" to lowercase. Even though Windows is case 
   insensitive, this causes problem to programs inside MSYS. 
   This step can be quickly done inside the MSYS shell typing this:

      mkdir /tmp/scilibs
      mv /c/scilab/bin/LibSci* /tmp/scilibs
      cd /tmp/scilibs
      for i in `ls Lib*`; do
         mv $i /c/scilab/bin/`echo $i | tr A-Z a-z`;
      done 

4) Enter the toolbox's toplevel directory, and type:

      ./configure
      make
      make install

5) For some versions of libtool/automake you may have to install the 
   DLL of the toolbox by hand:

      cp src/.libs/libsimple*.dll /c/scilab/contrib/simple/libsimple.dll


Now enter Scilab and execute the "loader.sce" script placed in the 
directory where the toolbox was installed.


To Adapt the Package for Yourself
=================================

First make sure you have the latest autoconf, automake and libtool
installed in your system. They can be downloaded respectively at:
   http://www.gnu.org/software/automake/
   http://www.gnu.org/software/autoconf/
   http://www.gnu.org/software/libtool/

Just in case you want to learn more about the GNU Autotools, the
following book is excellent:
   http://sources.redhat.com/autobook/

But you don't need to read it to get started. Just you follow these steps:


1- Write your C routine. The sourcecode and inteface code are in
   ".c" files under the "src" directory. The soma_int.c contains a
   very simple example of a routine called "soma" that returns the
   sum of its two arguments.

2- define a name for your package, say "mypack".

3- edit config/lib_build.sce
   a) The only variables that you need to customize for your package are
   "lib_name", "sources", and  "table". They are pretty intuitive,
   just do something analogous to what's done for the "simple" toolbox.

4- edit configure.ac. 
   a) Change the lines:
         AC_INIT([simple], [1.2], [ricardofabbri@users.sf.net])
         AC_CONFIG_SRCDIR([soma_int.c])
      to
         AC_INIT([mypack], [1.0], [your_email@somewhere.com])
         AC_CONFIG_SRCDIR([your_c_file.c])

      Of course I wrote example names. Put your real data instead of
      "mypack", "your_email@somewhere.com".  The file "your_c_file.c" is
      any one of your source files, but just one.

   b) In the lines:
         AC_PREFIX_DEFAULT([SCI/contrib/simple])
         if test "x$prefix"  = xNONE; then 
             prefix="$SCI/contrib/simple"
         fi
      replace "simple" by "mypack" (your package name).

7- Remove the "src/libsimple.c" file

8- Edit the file "config/loader.sce.in"
   a) place any custom code to be executed when your toolbox loads
   b) edit the lines specific to the SIMPLE toolbox. Put your specific
   information instead.

9- type ./bootstrap --all

If everything goes well, your package is ready and you will be able to type:

./configure 
make
make install


ABOUT THE BOOTSTRAP PROCESS
===========================

First, the script "bootstrap" gets your definitions in
config/lib_build.sce and generates a Makefile.am from
your Makefile.am.input (in the src dir), using the script
config/subst_input_files.sh.  This is just for convenience, since
when your package grows you won't neet to enter the sources in both
Makefile.am and lib_build.sce, but only once.

After that, the script runs autoconf, automake and libtool, together
with any parameters that these packages need. This will create many
files, mainly the configure script and the final Makefiles.

You must run bootstrap when :
   - a new ".c" source is added to "lib_build.sce".  In this case, you
     must use the "--all" parameter, as in step 9 above
   - you edit Makefile.am.input of the src directory 

When you edit "configure.ac" or the toplevel "Makefile.am", you must
run the "autoreconf" script.


That's It!
==========

For a more complex example, checkout the Scilab Image Processing
toolbox (SIP) at http://siptoolbox.sf.net 

Please send comments and bugreports to the proper mailing list at:
  http://sourceforge.net/mail/?group_id=68055