ascend/trunk/INSTALL.txt

BUILDING AND INSTALLING ASCEND

Thanks for downloading ASCEND! We hope you'll find it straight-
forward to set up and run ASCEND. If you have any comments on
your experience with this, we're very keen to hear about that.
Please check out the up-to-date contact details at:
https://ascendserver.cheme.cmu.edu/wiki/

There are older versions of this document, which include instructions
on how to build ASCEND with GNU Autotools. This may or may not work
with the version you are currently looking at.
https://ascendserver.cheme.cmu.edu/svn/ascend/code/branches/extfn/INSTALL.txt?view=log

-----
BUILDING ON LINUX AND WINDOWS

To build ASCEND we recommend using SCons. This is supported
both on Windows (using the MinGW toolset), Mac OS X and Linux.

ASCEND provides two possible interfaces. The older, more mature
GUI is based on Tcl/Tk. A newer interface that is more in keeping
with modern GUI design is implemented using PyGTK, but it is still
missing some functionality and actively being developed.

Using SCons 0.96.92 or newer, see your build options by typing

  scons -Qh

You can add your build options to a file in this directory
which you can create, called 'config.py'. Otherwise you can
specify your build options via the commandline. By default they will
be recorded in the file 'options.cache', so watch out for that if scons
seems to not be doing what you expected.

Then to build ASCEND, type

  scons

SCons will tell you what version(s) of ASCEND it is able to build, and then
proceed to start the build. The PyGTK interface requires Python (which is
already present if you have SCons!). The Tcl/Tk interface requires that you 
have Tcl/Tk and TkTable installed on your system.

For updates on this information, and PLATFORM-SPECIFIC INFORMATION, please check
http://ascendserver.cheme.cmu.edu/wiki/index.php/BuildingAscend

For specific information on building the Python interface and
setting up the PyGTK GUI, please see
http://ascendserver.cheme.cmu.edu/wiki/index.php/PythonWrapper

------
BUILDING ON SOLARIS

Some work has been done on building on Solaris, using Python 2.3. At present
it's pretty close but not yet stable. If you can help out, let us know.

------
RUNNING FOR THE FIRST TIME

If you've build ASCEND from source, you don't need to 'install'
it before you can run it. The main issue with running from the
source directories is that you need to set various environment
variables: 

ASCENDLIBRARY
  Location of the 'models' directory, eg ~/src/ascend-NNN/models

LD_LIBRARY_PATH
  Must contain the paths to the ascend shared libraries, in
  particular libascend.so, or for the Tcl/Tk interface, also
  libascendtcl.so.
  
It can often be easier to simply install in your home directory
as shown below.

------
ISSUES WITH THE TCL/TK INTERFACE

It can sometimes be a bit challenging to build the Tcl/Tk
interface. ASCEND can run with Tcl/Tk version 8.4 but it is more stable when
using Tcl/Tk version 8.3. 

A suggested approach in this case is to download and install the 'ActiveTcl'
distribution, version 8.3.5, and to install it in ~/activetcl.
http://downloads.activestate.com/ActiveTcl/Windows/8.3.5/

Then, you should be able to build the Tcl/Tk interface as shown:

  export LD_LIBRARY_PATH=~/activetcl/lib:~/activetcl/lib/Tktable2.8
  scons TCL=~/activetcl

See also the TCL_LIB and TK_LIB flags (scons -Qh).

------
INSTALLING ON LINUX

To then install ASCEND, you will need to have write access to the 
directories INSTALL_* as specified in your SCons configuration.
You can then type:

  scons install
    
The simplest way to install ASCEND 'off-root' is something like:

  scons INSTALL_PREFIX=~/ascroot
  
Note that if you install (or run) ASCEND off-root, you need to
ensure that Linux can access the shared libraries. For example,
in the above case, you would need to add

  export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/ascroot/lib

------
INSTALLING ON WINDOWS

To build a Windows installer (a 'setup.exe') for the PyGTK GUI,
you will need to have the NSIS installer-creator installed on
your system (which is free, at http://nsis.sf.net/). Then you 
should simply need to type

  scons installer

This will leave an installer package named 'ascend-NNNNN.exe'
in the pygtk/interface directory, with NNNNN being the version number specified
at the top of the SConstruct file.

------
A NOTE ABOUT PREFERENCES

ASCEND PyGTK GUI stores your preferences in the file ~/.ascend.ini.
The Tcl/Tk GUI creates a file under ~/ascdata.
You may wish to check these files if ASCEND seems to be doing 
something you didn't expect.

------
CREATING AN RPM/DEB PACKAGE

Many users prefer to keep their systems clear of unpackaged
software. For this reason, we aim to provide the ability to build 
ASCEND as an RPM package. There is a "SPEC" file included in the
source tree. If you have a source package, such as for example
ascend-NNNNN.tar.bz2, place it in your home directory, then
type the following

  rpmbuild -ta ascend-NNNNN.tar.bz2

This will pull out the 'spec' from from the source package, 
which hopefully will be up to date in correspondance with the
package version number NNNNN.

You will then be able to install ASCEND using something like

  rpm -i ~/rpm/ascend-NNNNN-0.jdpipe.i386.rpm

Instructions for buildin the .deb package are available on the
ASCEND wiki.

NOTE: occasionally the 'ascend.spec' file may need to be updated
if changes have been made to the 'ascend.spec.in' file. Check
the implementation details in the SConstruct file.

------
GETTING SUPPORT AND FURTHER INFORMATION

For support with ASCEND, details of mailing lists and other
useful information, please visit

ASCEND user's website:
http://ascend.cheme.cmu.edu/

ASCEND developer's wiki:
https://ascendserver.cheme.cmu.edu/wiki/

1	johnpye	438	BUILDING AND INSTALLING ASCEND
2	aw0a	1
3	johnpye	438	Thanks for downloading ASCEND! We hope you'll find it straight-
4			forward to set up and run ASCEND. If you have any comments on
5			your experience with this, we're very keen to hear about that.
6			Please check out the up-to-date contact details at:
7	jpye	1318	https://ascendserver.cheme.cmu.edu/wiki/
8	johnpye	146
9	johnpye	438	There are older versions of this document, which include instructions
10			on how to build ASCEND with GNU Autotools. This may or may not work
11	johnpye	476	with the version you are currently looking at.
12	jpye	1318	https://ascendserver.cheme.cmu.edu/svn/ascend/code/branches/extfn/INSTALL.txt?view=log
13	johnpye	146
14	johnpye	438	-----
15			BUILDING ON LINUX AND WINDOWS
16	johnpye	146
17	jpye	2145	To build ASCEND we recommend using SCons. This is supported
18			both on Windows (using the MinGW toolset), Mac OS X and Linux.
19	aw0a	1
20	johnpye	438	ASCEND provides two possible interfaces. The older, more mature
21			GUI is based on Tcl/Tk. A newer interface that is more in keeping
22			with modern GUI design is implemented using PyGTK, but it is still
23	johnpye	683	missing some functionality and actively being developed.
24	aw0a	1
25	johnpye	683	Using SCons 0.96.92 or newer, see your build options by typing
26	aw0a	1
27	johnpye	559	scons -Qh
28	aw0a	1
29	johnpye	438	You can add your build options to a file in this directory
30	johnpye	765	which you can create, called 'config.py'. Otherwise you can
31			specify your build options via the commandline. By default they will
32			be recorded in the file 'options.cache', so watch out for that if scons
33			seems to not be doing what you expected.
34	aw0a	1
35	johnpye	438	Then to build ASCEND, type
36	aw0a	1
37	johnpye	559	scons
38	aw0a	1
39	johnpye	683	SCons will tell you what version(s) of ASCEND it is able to build, and then
40			proceed to start the build. The PyGTK interface requires Python (which is
41			already present if you have SCons!). The Tcl/Tk interface requires that you
42			have Tcl/Tk and TkTable installed on your system.
43	aw0a	1
44	johnpye	683	For updates on this information, and PLATFORM-SPECIFIC INFORMATION, please check
45	jpye	1318	http://ascendserver.cheme.cmu.edu/wiki/index.php/BuildingAscend
46	aw0a	1
47	johnpye	438	For specific information on building the Python interface and
48			setting up the PyGTK GUI, please see
49	jpye	1318	http://ascendserver.cheme.cmu.edu/wiki/index.php/PythonWrapper
50	aw0a	1
51	johnpye	438	------
52	johnpye	988	BUILDING ON SOLARIS
53
54			Some work has been done on building on Solaris, using Python 2.3. At present
55			it's pretty close but not yet stable. If you can help out, let us know.
56
57			------
58	johnpye	559	RUNNING FOR THE FIRST TIME
59
60			If you've build ASCEND from source, you don't need to 'install'
61			it before you can run it. The main issue with running from the
62			source directories is that you need to set various environment
63			variables:
64
65			ASCENDLIBRARY
66			Location of the 'models' directory, eg ~/src/ascend-NNN/models
67
68			LD_LIBRARY_PATH
69			Must contain the paths to the ascend shared libraries, in
70			particular libascend.so, or for the Tcl/Tk interface, also
71			libascendtcl.so.
72
73			It can often be easier to simply install in your home directory
74			as shown below.
75
76			------
77			ISSUES WITH THE TCL/TK INTERFACE
78
79			It can sometimes be a bit challenging to build the Tcl/Tk
80	johnpye	649	interface. ASCEND can run with Tcl/Tk version 8.4 but it is more stable when
81			using Tcl/Tk version 8.3.
82
83			A suggested approach in this case is to download and install the 'ActiveTcl'
84	johnpye	559	distribution, version 8.3.5, and to install it in ~/activetcl.
85			http://downloads.activestate.com/ActiveTcl/Windows/8.3.5/
86
87			Then, you should be able to build the Tcl/Tk interface as shown:
88
89			export LD_LIBRARY_PATH=~/activetcl/lib:~/activetcl/lib/Tktable2.8
90			scons TCL=~/activetcl
91
92	johnpye	649	See also the TCL_LIB and TK_LIB flags (scons -Qh).
93
94	johnpye	559	------
95	johnpye	438	INSTALLING ON LINUX
96	aw0a	1
97	johnpye	438	To then install ASCEND, you will need to have write access to the
98	johnpye	765	directories INSTALL_* as specified in your SCons configuration.
99			You can then type:
100	aw0a	1
101	johnpye	559	scons install
102
103			The simplest way to install ASCEND 'off-root' is something like:
104	aw0a	1
105	johnpye	559	scons INSTALL_PREFIX=~/ascroot
106
107			Note that if you install (or run) ASCEND off-root, you need to
108			ensure that Linux can access the shared libraries. For example,
109			in the above case, you would need to add
110
111			export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/ascroot/lib
112
113	johnpye	438	------
114			INSTALLING ON WINDOWS
115	aw0a	1
116	johnpye	476	To build a Windows installer (a 'setup.exe') for the PyGTK GUI,
117			you will need to have the NSIS installer-creator installed on
118			your system (which is free, at http://nsis.sf.net/). Then you
119			should simply need to type
120	aw0a	1
121	johnpye	649	scons installer
122	johnpye	476
123	johnpye	683	This will leave an installer package named 'ascend-NNNNN.exe'
124			in the pygtk/interface directory, with NNNNN being the version number specified
125			at the top of the SConstruct file.
126	johnpye	476
127	johnpye	438	------
128	johnpye	765	A NOTE ABOUT PREFERENCES
129
130			ASCEND PyGTK GUI stores your preferences in the file ~/.ascend.ini.
131			The Tcl/Tk GUI creates a file under ~/ascdata.
132			You may wish to check these files if ASCEND seems to be doing
133			something you didn't expect.
134
135			------
136	johnpye	438	CREATING AN RPM/DEB PACKAGE
137	aw0a	1
138	johnpye	438	Many users prefer to keep their systems clear of unpackaged
139			software. For this reason, we aim to provide the ability to build
140	johnpye	559	ASCEND as an RPM package. There is a "SPEC" file included in the
141	johnpye	476	source tree. If you have a source package, such as for example
142			ascend-NNNNN.tar.bz2, place it in your home directory, then
143			type the following
144	aw0a	1
145	johnpye	559	rpmbuild -ta ascend-NNNNN.tar.bz2
146	aw0a	1
147	johnpye	438	This will pull out the 'spec' from from the source package,
148			which hopefully will be up to date in correspondance with the
149			package version number NNNNN.
150	aw0a	1
151	johnpye	438	You will then be able to install ASCEND using something like
152	aw0a	1
153	johnpye	559	rpm -i ~/rpm/ascend-NNNNN-0.jdpipe.i386.rpm
154	aw0a	1
155	jpye	2145	Instructions for buildin the .deb package are available on the
156			ASCEND wiki.
157	aw0a	1
158	johnpye	476	NOTE: occasionally the 'ascend.spec' file may need to be updated
159			if changes have been made to the 'ascend.spec.in' file. Check
160			the implementation details in the SConstruct file.
161
162	johnpye	438	------
163			GETTING SUPPORT AND FURTHER INFORMATION
164	aw0a	1
165	johnpye	438	For support with ASCEND, details of mailing lists and other
166			useful information, please visit
167	aw0a	1
168	johnpye	438	ASCEND user's website:
169			http://ascend.cheme.cmu.edu/
170	aw0a	1
171	johnpye	438	ASCEND developer's wiki:
172	jpye	1318	https://ascendserver.cheme.cmu.edu/wiki/
173	johnpye	989