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://pse.cheme.cmu.edu/wiki/view/Ascend/WebHome

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://pse.cheme.cmu.edu/svn-view/ascend/code/trunk/INSTALL.txt?view=log

-----
BUILDING ON LINUX AND WINDOWS

To build ASCEND we now recommend using SCons. This is supported
both on Windows (using the MinGW toolset) and Linux. Build scripts for using
jam and GNU Autotools are also provided although these scripts will not allow
you access to the full range of ASCEND functionality. The Autotools
scripts will only build the tcl/tk interface version.

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'.

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
https://pse.cheme.cmu.edu/wiki/view/Ascend/BuildingAscend

For specific information on building the Python interface and
setting up the PyGTK GUI, please see
https://pse.cheme.cmu.edu/wiki/view/Ascend/PythonWrapper

------
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_DATA, INSTALL_BIN 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.

------
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

Debian/Unbuntu users should find that they can create a usable
.deb package using the tool 'alien'. We haven't got native
support for the generation of .deb packages at this stage.

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://pse.cheme.cmu.edu/wiki/view/Ascend/WebHome
1	BUILDING AND INSTALLING ASCEND
2
3	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	https://pse.cheme.cmu.edu/wiki/view/Ascend/WebHome
8
9	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	with the version you are currently looking at.
12	https://pse.cheme.cmu.edu/svn-view/ascend/code/trunk/INSTALL.txt?view=log
13
14	-----
15	BUILDING ON LINUX AND WINDOWS
16
17	To build ASCEND we now recommend using SCons. This is supported
18	both on Windows (using the MinGW toolset) and Linux. Build scripts for using
19	jam and GNU Autotools are also provided although these scripts will not allow
20	you access to the full range of ASCEND functionality. The Autotools
21	scripts will only build the tcl/tk interface version.
22
23	ASCEND provides two possible interfaces. The older, more mature
24	GUI is based on Tcl/Tk. A newer interface that is more in keeping
25	with modern GUI design is implemented using PyGTK, but it is still
26	missing some functionality and actively being developed.
27
28	Using SCons 0.96.92 or newer, see your build options by typing
29
30	scons -Qh
31
32	You can add your build options to a file in this directory
33	which you can create, called 'config.py'.
34
35	Then to build ASCEND, type
36
37	scons
38
39	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
44	For updates on this information, and PLATFORM-SPECIFIC INFORMATION, please check
45	https://pse.cheme.cmu.edu/wiki/view/Ascend/BuildingAscend
46
47	For specific information on building the Python interface and
48	setting up the PyGTK GUI, please see
49	https://pse.cheme.cmu.edu/wiki/view/Ascend/PythonWrapper
50
51	------
52	RUNNING FOR THE FIRST TIME
53
54	If you've build ASCEND from source, you don't need to 'install'
55	it before you can run it. The main issue with running from the
56	source directories is that you need to set various environment
57	variables:
58
59	ASCENDLIBRARY
60	Location of the 'models' directory, eg ~/src/ascend-NNN/models
61
62	LD_LIBRARY_PATH
63	Must contain the paths to the ascend shared libraries, in
64	particular libascend.so, or for the Tcl/Tk interface, also
65	libascendtcl.so.
66
67	It can often be easier to simply install in your home directory
68	as shown below.
69
70	------
71	ISSUES WITH THE TCL/TK INTERFACE
72
73	It can sometimes be a bit challenging to build the Tcl/Tk
74	interface. ASCEND can run with Tcl/Tk version 8.4 but it is more stable when
75	using Tcl/Tk version 8.3.
76
77	A suggested approach in this case is to download and install the 'ActiveTcl'
78	distribution, version 8.3.5, and to install it in ~/activetcl.
79	http://downloads.activestate.com/ActiveTcl/Windows/8.3.5/
80
81	Then, you should be able to build the Tcl/Tk interface as shown:
82
83	export LD_LIBRARY_PATH=~/activetcl/lib:~/activetcl/lib/Tktable2.8
84	scons TCL=~/activetcl
85
86	See also the TCL_LIB and TK_LIB flags (scons -Qh).
87
88	------
89	INSTALLING ON LINUX
90
91	To then install ASCEND, you will need to have write access to the
92	directories INSTALL_DATA, INSTALL_BIN as specified in your
93	SCons configuration. You can then type
94
95	scons install
96
97	The simplest way to install ASCEND 'off-root' is something like:
98
99	scons INSTALL_PREFIX=~/ascroot
100
101	Note that if you install (or run) ASCEND off-root, you need to
102	ensure that Linux can access the shared libraries. For example,
103	in the above case, you would need to add
104
105	export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/ascroot/lib
106
107	------
108	INSTALLING ON WINDOWS
109
110	To build a Windows installer (a 'setup.exe') for the PyGTK GUI,
111	you will need to have the NSIS installer-creator installed on
112	your system (which is free, at http://nsis.sf.net/). Then you
113	should simply need to type
114
115	scons installer
116
117	This will leave an installer package named 'ascend-NNNNN.exe'
118	in the pygtk/interface directory, with NNNNN being the version number specified
119	at the top of the SConstruct file.
120
121	------
122	CREATING AN RPM/DEB PACKAGE
123
124	Many users prefer to keep their systems clear of unpackaged
125	software. For this reason, we aim to provide the ability to build
126	ASCEND as an RPM package. There is a "SPEC" file included in the
127	source tree. If you have a source package, such as for example
128	ascend-NNNNN.tar.bz2, place it in your home directory, then
129	type the following
130
131	rpmbuild -ta ascend-NNNNN.tar.bz2
132
133	This will pull out the 'spec' from from the source package,
134	which hopefully will be up to date in correspondance with the
135	package version number NNNNN.
136
137	You will then be able to install ASCEND using something like
138
139	rpm -i ~/rpm/ascend-NNNNN-0.jdpipe.i386.rpm
140
141	Debian/Unbuntu users should find that they can create a usable
142	.deb package using the tool 'alien'. We haven't got native
143	support for the generation of .deb packages at this stage.
144
145	NOTE: occasionally the 'ascend.spec' file may need to be updated
146	if changes have been made to the 'ascend.spec.in' file. Check
147	the implementation details in the SConstruct file.
148
149	------
150	GETTING SUPPORT AND FURTHER INFORMATION
151
152	For support with ASCEND, details of mailing lists and other
153	useful information, please visit
154
155	ASCEND user's website:
156	http://ascend.cheme.cmu.edu/
157
158	ASCEND developer's wiki:
159	https://pse.cheme.cmu.edu/wiki/view/Ascend/WebHome