File: INSTALL.txt

package info (click to toggle)
python-visual 1:5.12-1.6
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd, stretch
  • size: 7,708 kB
  • ctags: 7,635
  • sloc: cpp: 15,593; sh: 9,615; ansic: 6,631; python: 4,737; makefile: 384
file content (256 lines) | stat: -rw-r--r-- 12,881 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
The purpose of this file is to fully document the installation
procedure for VPython from source on Linux. Specific installers
for Windows and Mac are available at vpython.org. See HACKING.txt
for details on how to do development work with the source code for
Linux.

Windows and Mac builds are now special to them; 
see VCBuild/VCBuild.txt and MAC-OSX.txt.

Table of Contents:
I:   Prerequisites
II:  Configuration
III: Building
IV:  Final Installation
V:   Troubleshooting

I.  Prerequisites:
	Most or all of these may be provided by your operating system 
	distributor.  In every case, you must have the "developer" version
	of the packages to ensure that the required header files are 
	available.
	
	GNU g++ version 3.2.x or >= 3.3.1 (3.4.6 reccomended) (gcc.gnu.org).
	An implementation of OpenGL.
	The Boost C++ libraries version 1.31 and higher (1.33.1 reccomended)
		(www.boost.org). Note that 1.31 is required if you are using Python 
		2.3 or higher, and is recommended in any case due to getting much
		better error messages. 1.32.0 or higher is required if you want to use
		GNU G++ 3.4.0 or higher to build the suite.
		You need libboost-python-dev, libboost-signals-dev, and libboost-thread-dev.
		*** It is an unfortunate fact of life that the Boost libraries that
		*** deal with Python have names that do not reflect what version of
		*** Python they were built for and with. You have to be careful to
		*** install Boost Python libraries that were built for your version of Python.
	
	BUILDING BOOST
	The Boost libraries are extensions to C++. Among the libraries
	are python and thread libraries used by Visual. The python library
	makes connections between Python and C++.

	It is possible to build the Boost libraries needed by Visual from source. 
	However, the process can take a long time, so precompiled files are 
	available in the Developers section. See VCBuild.txt for Windows details.
	
	You also need the threadpool resource: sourceforge.net/projects/threadpool.
	If you are using the 1_35_0 Boost libraries, you can use version 0.2.4 which
	is included in the package (in dependencies). If you use a different version
	of the Boost libraries, you need to get an appropriate threadpool version and
	replace the files in "dependencies/threadpool/include". Copy into the include
	directory the contents of the boost directory in the threadpool package,
	which includes a directory named "threadpool" and a file "threadpool.hpp".
	
	Problem bulding; found this on the web:
	"Furthermore building pyrap with boost-1.37 and gcc-4.3.2 gave an error 
	due to a missing include. The following patch has to be applied to boost:"

	In /usr/include (probably), change /boost/python/detail/translate_exception.hpp
	===================================================================
	--- boost/python/detail/translate_exception.hpp (revision 50228)
	+++ boost/python/detail/translate_exception.hpp (working copy)
	@@ -9,6 +9,7 @@
 
	 # include <boost/call_traits.hpp>
 	# include <boost/type_traits/add_const.hpp>
	+# include <boost/type_traits/add_reference.hpp>
 
	 # include <boost/function/function0.hpp>
	--------------------------------------
	(That is, add "# include <boost/type_traits/add_reference.hpp>" after the
	statement "# include <boost/type_traits/add_const.hpp>".)
	
	Although the boost-1.39 file does not include <boost/type_traits/add_reference.hpp>,
	Visual nevertheless builds okay on a Mac using boost-1.39. Have not tried
	on other platforms.
		
	Python 2.2.x or 2.3.x or 2.4.x or 2.5.x (www.python.org), including
		the development (dev) package.
	numpy (numpy.sourceforge.net).
	On Ubuntu 7.10, the only package for numpy was for Python 2.4, even though
	it is Python 2.5 which is installed by default. So it was necessary to download
	numpy (www.scipy.org/Download). And it was also necessary to install the
	packages libboost-python-dev, libboost-signals-dev, and libboost-thread-dev
	before executing in the numpy folder "python setup.py install".
	
	The autoconf, automake, libtool, and pkg-config packages.
	
	Generically, key libraries are these:
		gtkmm (www.gtkmm.org), which depends on gtk2 (www.gtk.org)
		gtkglext and gtkglextmm 1.2.x (gtkglext.sourceforge.net)
	GTK2 (sometimes called GTK+) is a platform-independent library for creating
	graphical user interfaces. It is designed for programs written in C. 
	GTKMM is a "wrapper" to make GTK2 accessible to programs written in C++.
		
	Here is a list of all the libraries involved. In many cases a library is 
	automatically installed by a package manager when a requested library depends on it:
	
	For Ubuntu 8.04, installing libgtkglextmm-x11-dev brought in everything
	except for libglademm-2.4, which also must be installed. 
	
	For Ubuntu 9.04:
	1) automake gets autoconf
	2) libgtkglextmm-x11-dev gets libatk1.0, libcairo2, libglib2.0, libgtk2.0,
	       libgtkglext1, libgtkglextmm-x11-1.2, libpango1.0
	3) libgtkmm-2.4-dev gets libcairomm-1.0, libglibmm-2.4, libpangomm-1.4, libsigc++-2.0
	4) libglademm-2.4-dev gets the rest

	On Ubuntu 8.04, the packages are named (not including the "dev" part of the name):
	   libgtk-2.0, libatk-1.0, atkmm-1.6, libsigc++-2.0, 
	   libgtkmm-2.4, gdkmm-2.4, libglib-2.0, libglibmm-2.4, 
	   libpango-1.0, pangomm-1.4, libfreetype2,  
	   libgtkglext1, libgtkglextmm-x11-1.2, libcairo2, libcairomm-1.0, 
	   libglade2, libglademm-2.4
	Ubuntu 8.04 package manager doesn't list freetype2, (lib)atkmm, 
	(lib)gdkmm, (lib)pangomm. But there exist these directories; maybe these
	components are now part of Ubuntu and so don't show up in the package manager.
		/usr/include/atkmm-1.6, /usr/lib/gdkmm-2.4, /usr/include/gdkmm-2.4.
		/usr/include/pangomm-1.4
	
	On Ubuntu 7.10, the packages were named like this (not including "dev"):
	   gtk-2.0, atk-1.0, atkmm-1.6, sigc++-2.0, 
	   gtkmm-2.4, gdkmm-2.4, glib-2.0, glibmm-2.4, 
	   pango-1.0, pangomm-1.4, freetype2,  
	   gtkglext-1.0, gtkglextmm-1.2, cairo, cairomm-1.0, 
	   libglade-2.0, libglademm-2.4
	On Ubuntu 7.10, installing libgtkmm-2.4-dev and libglademm-2.4-dev installs most
	of these libraries, except for atkmm, gdkmm, pangomm, gtkglext, and gtkglextmm.
	There is a gtkglext1-dev package, but no gtkglextmm.
		
	For Ubuntu 7.10, I was unable to install gtkglextmm from source. But at
	packages.ubuntu.com/source/gtkglextmm, from the older "edgy" distribution get
	libgtkglextmm1c2a (allow the default package manager to process the download), then
	libgtkglextmm1-dev. 

	To install gtkglextmm:
	1) Download the bz2 file.
	2) Unpack the file: tar -xjf gtkglextmm-1.2.0.tar.bz2
	3) cd to the unpacked directory
	4) ./configure
	5) make
	6) sudo make install

II.   Configuration
	It is NOT the case that simply running './configure' is likely to work,
	because Visual has to be linked to an appropriate Python, so read below.
	
	There have been significant changes in where 3rd-party software is stored on 
	Ubuntu 9.04. You probably want to use /usr/bin/python2.6 but store the Visual
	module in /usr/local/lib/python2.6/site-packages. To configure, do this in a
	folder parallel to vpython-core2:
	
	PYTHON=/usr/bin/python ../vpython-core2/configure --prefix=/usr/local/lib
	
	You will also need to copy vpython-core2/src/gtk2/site-packages.pth to
	/usr/lib/python2.6/dist-packages to put /usr/local/lib/python2.6/site-packages
	on the Python search path.
	
	In src/gtk2 there is a simple non-autoconf makefile for Ubuntu 8 as of Nov. 2008.
	It is unlikely to be kept up to date, but it gives an example of the basic
	elements of what the rather complex autoconf machinery needs to produce.	

	However, configure also provides a large number of options and is sensitive to 
	several environment variables to properly configure VPython for unique use cases. 
	Additionally, it is a good idea to build VPython in a directory separate from the
	source tree.  Just run configure with the fully-qualified path to it, eg (from a
	directory alongside visual-2.9) `../visual-2.9/configure`
	
	Run `configure --help` for the complete list of options and brief descriptions.
	
	If you have multiple versions of Python installed, and the one named 'python' that
	is first on your PATH (identified with `which python`) is not the one you want to 
	build Visual for, specify the correct interpreter by setting the PYTHON
	environment variable to the desired interpreter's full path.
	
	If you have multiple versions of GNU G++ installed, and the default is inadequate
	for VPython, specify the correct one by setting the CXX environment variable to
	its fully-qualified path.
	
	You should generally supply the --prefix option to cause Visual to be installed to
	the same prefix that Python is installed (default is /usr/local).
	
	On Linux, do this: which python
	Make a note of the prefix preceding /bin/python, typically /usr or /usr/local.
	
	It is useful to place the visual folder and a folder named "build" at the same level,
	and configure and make in the build folder by "cd build", then do this:	
	(a) If prefix is /usr/local, execute
     	../visual-x.x.x/configure
	(b) If prefix is something else, and Visual can go into prefix/lib/python/site-packages, execute
     	../visual-x.x.x/configure --prefix=prefix
	(c) If you want to use a different version of Python than the one found with "which python",
   		or (b) is not appropriate, specify both the particular Python and where to install Visual:
      	PYTHON=/somewhere1/bin/python ../visual-x.x.x/configure --prefix=/somewhere2
	If "somewhere1" and "somewhere2" are different, you must also add the "somewhere2"
	directory to Python's module search path. For details, at www.python.org read section 4.1
	(Modifying Python's Search Path) in the section Installing Python Modules of the Python
	on-line documentation.
	
	Here is a specific example of case (c):
	PYTHON=/usr/bin/python ../visual-x.x.x/configure --prefix=/usr/local
	(This would make sense only if python has /usr/local/lib/site-packages on its 
	search path.)
	
	If you are only building VPython once, you may pass the option
	--disable-dependancy-tracking to make the build itself go a little faster.
	
	If your GNOME libraries are installed in a non-standard location (such as 
	/opt/gnome in SUSE), you must set the CPPFLAGS environment variable to 
	-I/other_prefix/include to ensure that you pick up the gtkglarea header files.
	
	Another interesting configuration is to install VPython into a prefix other than
	the same prefix that Python is installed in.  This may be useful to test your
	VPython programs with different versions of Visual on the same system
	simultaneously.  After choosing an approprate prefix, such as /home/jonathan, run
	configure as normally but specify the PYTHONPATH environment variable to be
	[prefix]/lib/python2.5/site-packages, replacing python2.5 with python2.2 if that
	is your interpreter. You must create this PYTHONPATH directory if it does not
	already exist.
	
III.  Build
	Just run 'make'.  
	
	Optionally, you may override the following variables by
	specifying them in the form VARIABLE=value as arguments to make:
	LDFLAGS, LIBS, CXXFLAGS, and CPPFLAGS affect options passed to the linker,
	compiler, and preprocessor, respectively.
	DESTDIR may be used to prepend DESTDIR to the 'prefix' specified when running
	configure. This option is mostly useful to binary redistributors of VPython.
	
	The makefiles support the following targets:
	all: (the default) compiles all the required software
	clean: deletes files created by the compiler
	distclean: deletes all files created by the configure and make programs.  This
		option is useful if you want to start over from a clean source tree.
	install: copies all required files in the locations specified by configure
	install-strip: Performs the 'install' target and strips the final object files.
		It also makes getting a backtrace impossible on most platforms. 

IV.  Install
	You must have write privileges to the installation directory to proceed.  Unless
	you are installing into your home directory, that generally means becoming root
	with a program like `sudo` or `su`. Just run `sudo make install`.
	
	Alternatively, you may run 'make install-strip' to install a somewhat smaller
	executable.

V:   Troubleshooting
	The single most likely cause of an error in the build is that one or more
	develoment header files could not be found.  VPython logs its configuration stage
	in config.log, and its build stage in src/build.log.  If the build fails you
	must read src/build.log to see what happened.  In the event that you cannot
	solve the problem, compress config.log and src/build.log and include them with
	your request for assistance to visualpython-users@lists.sourceforge.net.
	
	But before you do that, it is a good idea to read the archives of the mailing list
	since someone else has probably worked through your problem already.