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 requires Tcl/Tk version 8.3.5, which is not the
standard version on modern Linux distributions. 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

------
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 WITH_INSTALLER=1

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			interface. ASCEND requires Tcl/Tk version 8.3.5, which is not the
74			standard version on modern Linux distributions. A suggested
75			approach in this case is to download and install the 'ActiveTcl'
76			distribution, version 8.3.5, and to install it in ~/activetcl.
77			http://downloads.activestate.com/ActiveTcl/Windows/8.3.5/
78
79			Then, you should be able to build the Tcl/Tk interface as shown:
80
81			export LD_LIBRARY_PATH=~/activetcl/lib:~/activetcl/lib/Tktable2.8
82			scons TCL=~/activetcl
83
84			------
85	johnpye	438	INSTALLING ON LINUX
86	aw0a	1
87	johnpye	438	To then install ASCEND, you will need to have write access to the
88			directories INSTALL_DATA, INSTALL_BIN as specified in your
89			SCons configuration. You can then type
90	aw0a	1
91	johnpye	559	scons install
92
93			The simplest way to install ASCEND 'off-root' is something like:
94	aw0a	1
95	johnpye	559	scons INSTALL_PREFIX=~/ascroot
96
97			Note that if you install (or run) ASCEND off-root, you need to
98			ensure that Linux can access the shared libraries. For example,
99			in the above case, you would need to add
100
101			export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/ascroot/lib
102
103	johnpye	438	------
104			INSTALLING ON WINDOWS
105	aw0a	1
106	johnpye	476	To build a Windows installer (a 'setup.exe') for the PyGTK GUI,
107			you will need to have the NSIS installer-creator installed on
108			your system (which is free, at http://nsis.sf.net/). Then you
109			should simply need to type
110	aw0a	1
111	johnpye	559	scons WITH_INSTALLER=1
112	johnpye	476
113			This will leave an installer package named 'ascend-setup.exe'
114			in the pygtk/interface directory.
115
116	johnpye	438	------
117			CREATING AN RPM/DEB PACKAGE
118	aw0a	1
119	johnpye	438	Many users prefer to keep their systems clear of unpackaged
120			software. For this reason, we aim to provide the ability to build
121	johnpye	559	ASCEND as an RPM package. There is a "SPEC" file included in the
122	johnpye	476	source tree. If you have a source package, such as for example
123			ascend-NNNNN.tar.bz2, place it in your home directory, then
124			type the following
125	aw0a	1
126	johnpye	559	rpmbuild -ta ascend-NNNNN.tar.bz2
127	aw0a	1
128	johnpye	438	This will pull out the 'spec' from from the source package,
129			which hopefully will be up to date in correspondance with the
130			package version number NNNNN.
131	aw0a	1
132	johnpye	438	You will then be able to install ASCEND using something like
133	aw0a	1
134	johnpye	559	rpm -i ~/rpm/ascend-NNNNN-0.jdpipe.i386.rpm
135	aw0a	1
136	johnpye	438	Debian/Unbuntu users should find that they can create a usable
137			.deb package using the tool 'alien'. We haven't got native
138			support for the generation of .deb packages at this stage.
139	aw0a	1
140	johnpye	476	NOTE: occasionally the 'ascend.spec' file may need to be updated
141			if changes have been made to the 'ascend.spec.in' file. Check
142			the implementation details in the SConstruct file.
143
144	johnpye	438	------
145			GETTING SUPPORT AND FURTHER INFORMATION
146	aw0a	1
147	johnpye	438	For support with ASCEND, details of mailing lists and other
148			useful information, please visit
149	aw0a	1
150	johnpye	438	ASCEND user's website:
151			http://ascend.cheme.cmu.edu/
152	aw0a	1
153	johnpye	438	ASCEND developer's wiki:
154			https://pse.cheme.cmu.edu/wiki/view/Ascend/WebHome