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?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. Their fans
will also find build tools for jam and autotools. The autotools
build is still maintained for at least 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.

Using SCons 0.96.91 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.
The PyGTK interface requires Python (which is 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, 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-setup.exe'
in the pygtk/interface directory.

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