trunk/jam/ReadMe.txt


BUILDING ASCEND WITH JAM
------------------------

The files in this directory support building the ASCEND
libraries and executables using the jam* build tool.

The following files are included:

  Jamfile     - top-level Jamfile for building ASCEND

  Jamrules.in - configuration & custom build rules used by Jamfiles

  Jambase     - lightly customized version of standard build rules
              - primarily to shore up support for different compilers
              - optional in most cases

Other subdirectories of the source trees contain additional files used
to build ASCEND with jam:

  ../base/generic/Jamfile    - builds the ASCEND base libraries
  ../blas/Jamfile            - builds the blas library
  ../linpack/Jamfile         - builds the linpack library
  ../lsod/Jamfile            - builds the LSODE library
  ../tcltk98/generic/Jamfile - builds the tcltk98 executable
  ../tcltk98/generic/Jamrules_tcltk98.in
                             - configuration & custom build rules used
                               build the tcltk98 executable


The ASCEND jam build system intends to support building under Windows
using the MinGW/gcc, MSVC, Borland, and Watcom** compilers, and under
unix/linux using gcc/g77.  With use of the included custom Jambase file,
it should work with both the original and ftjam variants of jam.
However, the system was developed primarily using ftjam.  For best
results using your default Jambase, use of ftjam is recommended and
probably required.

Automatic processing of Jamrules.in and ../tcltk98/generic/Jamrules_tcltk98.in
by configure has now been implemented for systems supporting autoconf.
Configure should automatically set most necessary build options, although
some manual tweaking may still be necessary.  The configure.in file is
currently housed in ../base/unixAC213.  This may be relocated to a more
general location in the future.  For now, it is necessary to run autoconf &
configure from that directory, and then come back here to run jam.

Building ASCEND requires compatible C and FORTRAN compilers.  The official
distributions are built using gcc, which provides both of these.


Build Instructions - Linux/Unix
-------------------------------

You can build the Jam static libraries on Linux at present:

1. jam must be installed and configured for the compiler in use.

2. (a) If using autoconf, perform the following steps:

      - cd ../base/unixAC213
      - autoconf (if necessary)
      - ./configure {using the usual options such as --enable-gcc,
                     --with-tcl, --with-tk, --with-tktable}
      - cd ../../jam

   (b) If NOT using autoconf, manually copy the following files:
   
      - ./Jamrules.in  -->  ./Jamrules
      - ../tcltk98/generic/Jamrules_tcltk98.in  --> 
                    ../tcltk98/generic/Jamrules_tcltk98

3. If necessary or desired, manually edit the generated ./Jamrules and
   ../tcltk98/generic/Jamrules_tcltk98 files to set configuration and local
   directory options.  These settings are used by all the Jamfiles
   in the ASCEND source tree.

4. Run jam to generate the desired output:

       jam all       builds all libraries, executable, test suite
       jam libs      builds base, blas, linpack, and lsode static libs
       jam ascend    builds the ASCEND executable (will build libs as needed)
       jam test      builds the test suite (will build libs as needed)
       jam blas      builds the blas library
       jam linpack   builds the linpack library
       jam lsode     builds the lsode library

   NOTE - if there is a problem with jam setting basic options (e.g. CC = gcc),
          there are 2 possible workarounds.  First, use the custom Jambase
          file (jam -f Jambase ...) which more reliably sets these basic
          compilation options.  Or, explicitly specify the symbol in
          question (jam -sCC=gcc ...).  We have not quite figured out how
          to make sure these get set when defined in other than Jambase.

   All built files will be placed in ./CONFIGTYPE/PLATFORM where
          CONFIGTYPE = Debug, Release
          PLATFORM   = linux, mingw, bcc, msvc, mingw, watcom


Installation of the executables, libraries and headers is under development.
Installation should be assumed not to work at this time.


Build Instructions - Windows
----------------------------

Same as for Linux/Unix above, except you will need to follow 2b since 
the autotools are not generally available.


Notes
-----

* jam is an open source, multi-platform build tool
  which is available in several flavors.  These include
  the original (http://www.perforce.com) and ftjam
  (http://www.freetype.org/jam/index.html) variants,
  among others.

** Currently, Open Watcom 1.3 can compile the ASCEND sources
  and build the libraries.  However, it does not supply the required
  IEEE math functions isnan() and copysign().  At present, ASCEND does
  not supply these, so the user must provide these functions to use
  the libraries under Watcom.


For more information on building ASCEND using JAM
please see the Wiki document at
https://pse.cheme.cmu.edu/wiki/view/Ascend/Jam

1	johnpye	79
2	jds	129	BUILDING ASCEND WITH JAM
3	johnpye	79	------------------------
4
5	jds	129	The files in this directory support building the ASCEND
6	jds	40	libraries and executables using the jam* build tool.
7
8			The following files are included:
9
10	jds	129	Jamfile - top-level Jamfile for building ASCEND
11	jds	40
12	jds	129	Jamrules.in - configuration & custom build rules used by Jamfiles
13	jds	40
14	jds	129	Jambase - lightly customized version of standard build rules
15			- primarily to shore up support for different compilers
16			- optional in most cases
17	jds	40
18	jds	129	Other subdirectories of the source trees contain additional files used
19			to build ASCEND with jam:
20	jds	40
21	jds	129	../base/generic/Jamfile - builds the ASCEND base libraries
22			../blas/Jamfile - builds the blas library
23			../linpack/Jamfile - builds the linpack library
24			../lsod/Jamfile - builds the LSODE library
25			../tcltk98/generic/Jamfile - builds the tcltk98 executable
26			../tcltk98/generic/Jamrules_tcltk98.in
27			- configuration & custom build rules used
28			build the tcltk98 executable
29	jds	40
30	jds	129
31			The ASCEND jam build system intends to support building under Windows
32			using the MinGW/gcc, MSVC, Borland, and Watcom** compilers, and under
33			unix/linux using gcc/g77. With use of the included custom Jambase file,
34			it should work with both the original and ftjam variants of jam.
35			However, the system was developed primarily using ftjam. For best
36			results using your default Jambase, use of ftjam is recommended and
37			probably required.
38
39			Automatic processing of Jamrules.in and ../tcltk98/generic/Jamrules_tcltk98.in
40			by configure has now been implemented for systems supporting autoconf.
41			Configure should automatically set most necessary build options, although
42			some manual tweaking may still be necessary. The configure.in file is
43			currently housed in ../base/unixAC213. This may be relocated to a more
44			general location in the future. For now, it is necessary to run autoconf &
45			configure from that directory, and then come back here to run jam.
46
47			Building ASCEND requires compatible C and FORTRAN compilers. The official
48			distributions are built using gcc, which provides both of these.
49
50
51			Build Instructions - Linux/Unix
52			-------------------------------
53
54			You can build the Jam static libraries on Linux at present:
55
56	jds	40	1. jam must be installed and configured for the compiler in use.
57
58	jds	129	2. (a) If using autoconf, perform the following steps:
59	jds	40
60	jds	129	- cd ../base/unixAC213
61			- autoconf (if necessary)
62			- ./configure {using the usual options such as --enable-gcc,
63			--with-tcl, --with-tk, --with-tktable}
64			- cd ../../jam
65
66			(b) If NOT using autoconf, manually copy the following files:
67
68			- ./Jamrules.in --> ./Jamrules
69			- ../tcltk98/generic/Jamrules_tcltk98.in -->
70			../tcltk98/generic/Jamrules_tcltk98
71
72			3. If necessary or desired, manually edit the generated ./Jamrules and
73			../tcltk98/generic/Jamrules_tcltk98 files to set configuration and local
74	jds	40	directory options. These settings are used by all the Jamfiles
75	jds	129	in the ASCEND source tree.
76	jds	40
77	jds	129	4. Run jam to generate the desired output:
78	jds	40
79	jds	129	jam all builds all libraries, executable, test suite
80			jam libs builds base, blas, linpack, and lsode static libs
81			jam ascend builds the ASCEND executable (will build libs as needed)
82			jam test builds the test suite (will build libs as needed)
83			jam blas builds the blas library
84			jam linpack builds the linpack library
85			jam lsode builds the lsode library
86
87			NOTE - if there is a problem with jam setting basic options (e.g. CC = gcc),
88			there are 2 possible workarounds. First, use the custom Jambase
89			file (jam -f Jambase ...) which more reliably sets these basic
90			compilation options. Or, explicitly specify the symbol in
91			question (jam -sCC=gcc ...). We have not quite figured out how
92			to make sure these get set when defined in other than Jambase.
93
94			All built files will be placed in ./CONFIGTYPE/PLATFORM where
95			CONFIGTYPE = Debug, Release
96			PLATFORM = linux, mingw, bcc, msvc, mingw, watcom
97
98
99			Installation of the executables, libraries and headers is under development.
100			Installation should be assumed not to work at this time.
101
102
103			Build Instructions - Windows
104			----------------------------
105
106			Same as for Linux/Unix above, except you will need to follow 2b since
107			the autotools are not generally available.
108
109
110	johnpye	79	Notes
111	jds	129	-----
112	jds	40
113			* jam is an open source, multi-platform build tool
114	johnpye	79	which is available in several flavors. These include
115			the original (http://www.perforce.com) and ftjam
116			(http://www.freetype.org/jam/index.html) variants,
117			among others.
118	jds	40
119	jds	129	** Currently, Open Watcom 1.3 can compile the ASCEND sources
120	johnpye	79	and build the libraries. However, it does not supply the required
121	jds	129	IEEE math functions isnan() and copysign(). At present, ASCEND does
122	johnpye	79	not supply these, so the user must provide these functions to use
123			the libraries under Watcom.
124	jds	40
125	jds	129
126			For more information on building ASCEND using JAM
127			please see the Wiki document at
128			https://pse.cheme.cmu.edu/wiki/view/Ascend/Jam
129