Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 288 lines (232 sloc) 14.365 kb
abaacc6 Add automake files to project.
bsherwood authored
1 The purpose of this file is to fully document the installation
74fc087 Update/improve documentation for developers and for those installing on ...
bsherwood authored
2 procedure for VPython from source on Linux. Specific installers
3 for Windows and Mac are available at vpython.org. See HACKING.txt
4 for details on how to do development work with the source code for
5 Linux.
abaacc6 Add automake files to project.
bsherwood authored
6
d3b0ed9 Advertise Windows and Mac build instructions
bsherwood authored
7 Windows and Mac builds are now special to them;
8 see VCBuild/VCBuild.txt and MAC-OSX.txt.
9
abaacc6 Add automake files to project.
bsherwood authored
10 Table of Contents:
11 I: Prerequisites
12 II: Configuration
13 III: Building
14 IV: Final Installation
15 V: Troubleshooting
16
17 I. Prerequisites:
18 Most or all of these may be provided by your operating system
19 distributor. In every case, you must have the "developer" version
20 of the packages to ensure that the required header files are
21 available.
064bfbb Additional info on building on Linux
bsherwood authored
22
f159463 Update install instructions;
jbrandmeyer authored
23 GNU g++ version 3.2.x or >= 3.3.1 (3.4.6 reccomended) (gcc.gnu.org).
bc34a39 Correct typo.
bsherwood authored
24 An implementation of OpenGL.
f159463 Update install instructions;
jbrandmeyer authored
25 The Boost C++ libraries version 1.31 and higher (1.33.1 reccomended)
fb58b91 Add needed information on tools needed for building on Windows.
bsherwood authored
26 (www.boost.org). Note that 1.31 is required if you are using Python
27 2.3 or higher, and is recommended in any case due to getting much
28 better error messages. 1.32.0 or higher is required if you want to use
abaacc6 Add automake files to project.
bsherwood authored
29 GNU G++ 3.4.0 or higher to build the suite.
5729e8e Add information on building on Ubuntu 8.04
bsherwood authored
30 You need libboost-python-dev, libboost-signals-dev, and libboost-thread-dev.
ec1fbcf More documentation, in part for Mac
bsherwood authored
31 *** It is an unfortunate fact of life that the Boost libraries that
32 *** deal with Python have names that do not reflect what version of
33 *** Python they were built for and with. You have to be careful to
3b638f4 More Mac documentation.
bsherwood authored
34 *** install Boost Python libraries that were built for your version of Python.
e70805f Need threadpool resource
bsherwood authored
35
cc0ed70 Add some commentary about Ubuntu 10.10
bsherwood authored
36 *********************************************
37 BUG on Ubuntu 10.10: The files /usr/lib/libgdkglextmm-x11-1.2.la and /usr/lib/libgtkglextmm-x11-1.2.la
38 specify dependence on libgdk_pixbuf-2.0.la, which does not exist. A workaround is
39 to edit /usr/lib/libgdkglextmm-x11-1.2.la and /usr/lib/libgtkglextmm-x11-1.2.la,
40 replacing libgdk_pixbuf-2.0.la (missing static library) with libgdk_pixbuf-2.0.so
41 (dynamically loaded library).
42 *********************************************
43
6b0c500 Improve documentation on building Boost
bsherwood authored
44 BUILDING BOOST
45 The Boost libraries are extensions to C++. Among the libraries
46 are python and thread libraries used by Visual. The python library
47 makes connections between Python and C++.
48
49 It is possible to build the Boost libraries needed by Visual from source.
db389f9 Add some documentation on building Boost libraries
bsherwood authored
50 See VCBuild.txt for Windows details. The basics are these, after cd-ing
51 into the unzipped Boost source, with a folder "build" beside the Boost source:
52
53 ./bootstrap.sh --with-python-version=3.1 --with-libraries=python,signals,thread
54
55 ./bjam --build-dir=../build --layout=versioned
6b0c500 Improve documentation on building Boost
bsherwood authored
56
dbd157f Provide information about threadpool includes
bsherwood authored
57 You also need the threadpool resource: sourceforge.net/projects/threadpool.
3613178 Include dependencies/threadpool in Linux package
bsherwood authored
58 If you are using the 1_35_0 Boost libraries, you can use version 0.2.4 which
59 is included in the package (in dependencies). If you use a different version
60 of the Boost libraries, you need to get an appropriate threadpool version and
61 replace the files in "dependencies/threadpool/include". Copy into the include
62 directory the contents of the boost directory in the threadpool package,
48242e8 Correct a typo dealing with threadpool files
bsherwood authored
63 which includes a directory named "threadpool" and a file "threadpool.hpp".
d2af4f0 Add comment about Boost problem
bsherwood authored
64
8be0c06 Be more explicit about the Boost problem
bsherwood authored
65 If you get this error in compiling cvisualmodule.cpp:
66
67 In file included from /usr/include/boost/python/exception_translator.hpp:12,
68 from ../../vpython-core2/src/python/cvisualmodule.cpp:12:
f00d4c2 Correct a typo
bsherwood authored
69 /usr/include/boost/python/detail/translate_exception.hpp:34:
70 error: expected nested-name-specifier before "add_reference"
d2af4f0 Add comment about Boost problem
bsherwood authored
71
8be0c06 Be more explicit about the Boost problem
bsherwood authored
72 You need to make this change:
73
f865c6c More careful documentation of dependencies.
bsherwood authored
74 In /usr/include (probably), change /boost/python/detail/translate_exception.hpp
d2af4f0 Add comment about Boost problem
bsherwood authored
75 ===================================================================
76 --- boost/python/detail/translate_exception.hpp (revision 50228)
77 +++ boost/python/detail/translate_exception.hpp (working copy)
78 @@ -9,6 +9,7 @@
79
4f34a6d Correct minor typo
bsherwood authored
80 # include <boost/call_traits.hpp>
d2af4f0 Add comment about Boost problem
bsherwood authored
81 # include <boost/type_traits/add_const.hpp>
82 +# include <boost/type_traits/add_reference.hpp>
83
4f34a6d Correct minor typo
bsherwood authored
84 # include <boost/function/function0.hpp>
d2af4f0 Add comment about Boost problem
bsherwood authored
85 --------------------------------------
f865c6c More careful documentation of dependencies.
bsherwood authored
86 (That is, add "# include <boost/type_traits/add_reference.hpp>" after the
87 statement "# include <boost/type_traits/add_const.hpp>".)
064bfbb Additional info on building on Linux
bsherwood authored
88
cf11d7c Improve documentation on needed font modules
bsherwood authored
89 Need Python 2.2.x or 2.3.x or 2.4.x or 2.5.x (www.python.org), including
064bfbb Additional info on building on Linux
bsherwood authored
90 the development (dev) package.
cf11d7c Improve documentation on needed font modules
bsherwood authored
91 Need Python modules Polygon, FontTools, and ttfquery, from pypi.python.org.
92 For each module, unpack and in a terminal cd to the module folder.
93 Execute "sudo python setup.py install" to build and install the module.
94 Need numpy (numpy.sourceforge.net).
95
064bfbb Additional info on building on Linux
bsherwood authored
96 On Ubuntu 7.10, the only package for numpy was for Python 2.4, even though
cf11d7c Improve documentation on needed font modules
bsherwood authored
97 it was Python 2.5 which is installed by default. So it was necessary to download
064bfbb Additional info on building on Linux
bsherwood authored
98 numpy (www.scipy.org/Download). And it was also necessary to install the
da6f626 Give added detail about installing on Ubuntu 8.04
bsherwood authored
99 packages libboost-python-dev, libboost-signals-dev, and libboost-thread-dev
064bfbb Additional info on building on Linux
bsherwood authored
100 before executing in the numpy folder "python setup.py install".
101
817b645 Improve listing of dependencies.
bsherwood authored
102 The autoconf, automake, libtool, and pkg-config packages.
064bfbb Additional info on building on Linux
bsherwood authored
103
104 Generically, key libraries are these:
105 gtkmm (www.gtkmm.org), which depends on gtk2 (www.gtk.org)
106 gtkglext and gtkglextmm 1.2.x (gtkglext.sourceforge.net)
107 GTK2 (sometimes called GTK+) is a platform-independent library for creating
108 graphical user interfaces. It is designed for programs written in C.
109 GTKMM is a "wrapper" to make GTK2 accessible to programs written in C++.
ec1fbcf More documentation, in part for Mac
bsherwood authored
110
064bfbb Additional info on building on Linux
bsherwood authored
111 Here is a list of all the libraries involved. In many cases a library is
dc01837 Further documentation
bsherwood authored
112 automatically installed by a package manager when a requested library depends on it:
da6f626 Give added detail about installing on Ubuntu 8.04
bsherwood authored
113
b05ec01 Add info about font handling modules needed
bsherwood authored
114 For Visual 5.3 and later, you need the Python modules FontTools, ttfquery, and Polygon.
cb81233 Give more info on ttfquery
bsherwood authored
115 Be sure to get ttfquery 1.0.4 or later.
116
117 Note The following copyright notice applies to the Polygon module when included in
118 the VPython distribution concerning Polygon:
b05ec01 Add info about font handling modules needed
bsherwood authored
119
120 "This distribution contains code from the GPC Library, and/or code
121 resulting from the use of the GPC Library. This usage has been
122 authorized by The University of Manchester, on the understanding
123 that the GPC-related features are used only in the context of this
124 distribution. It is not permitted to extract the GPC code from the
125 distribution as the basis for commercial exploitation, unless a
126 GPC Commercial Use Licence is obtained from The University of
127 Manchester, contact: http://www.cs.man.ac.uk/~toby/gpc/".
128
da6f626 Give added detail about installing on Ubuntu 8.04
bsherwood authored
129 For Ubuntu 8.04, installing libgtkglextmm-x11-dev brought in everything
379730a Add some dependency info for Ubuntu 9.04
bsherwood authored
130 except for libglademm-2.4, which also must be installed.
131
b5efc01 Explain what to do if there is an error in translate_exception.hpp
bsherwood authored
132 For Ubuntu 9.04-10.04:
0053a95 More about Ubuntu 9.04 dependencies
bsherwood authored
133 1) automake gets autoconf
134 2) libgtkglextmm-x11-dev gets libatk1.0, libcairo2, libglib2.0, libgtk2.0,
135 libgtkglext1, libgtkglextmm-x11-1.2, libpango1.0
136 3) libgtkmm-2.4-dev gets libcairomm-1.0, libglibmm-2.4, libpangomm-1.4, libsigc++-2.0
137 4) libglademm-2.4-dev gets the rest
da6f626 Give added detail about installing on Ubuntu 8.04
bsherwood authored
138
139 On Ubuntu 8.04, the packages are named (not including the "dev" part of the name):
140 libgtk-2.0, libatk-1.0, atkmm-1.6, libsigc++-2.0,
141 libgtkmm-2.4, gdkmm-2.4, libglib-2.0, libglibmm-2.4,
142 libpango-1.0, pangomm-1.4, libfreetype2,
143 libgtkglext1, libgtkglextmm-x11-1.2, libcairo2, libcairomm-1.0,
144 libglade2, libglademm-2.4
145 Ubuntu 8.04 package manager doesn't list freetype2, (lib)atkmm,
146 (lib)gdkmm, (lib)pangomm. But there exist these directories; maybe these
147 components are now part of Ubuntu and so don't show up in the package manager.
148 /usr/include/atkmm-1.6, /usr/lib/gdkmm-2.4, /usr/include/gdkmm-2.4.
149 /usr/include/pangomm-1.4
150
151 On Ubuntu 7.10, the packages were named like this (not including "dev"):
dc01837 Further documentation
bsherwood authored
152 gtk-2.0, atk-1.0, atkmm-1.6, sigc++-2.0,
ec1fbcf More documentation, in part for Mac
bsherwood authored
153 gtkmm-2.4, gdkmm-2.4, glib-2.0, glibmm-2.4,
154 pango-1.0, pangomm-1.4, freetype2,
da6f626 Give added detail about installing on Ubuntu 8.04
bsherwood authored
155 gtkglext-1.0, gtkglextmm-1.2, cairo, cairomm-1.0,
156 libglade-2.0, libglademm-2.4
064bfbb Additional info on building on Linux
bsherwood authored
157 On Ubuntu 7.10, installing libgtkmm-2.4-dev and libglademm-2.4-dev installs most
158 of these libraries, except for atkmm, gdkmm, pangomm, gtkglext, and gtkglextmm.
159 There is a gtkglext1-dev package, but no gtkglextmm.
da6f626 Give added detail about installing on Ubuntu 8.04
bsherwood authored
160
5729e8e Add information on building on Ubuntu 8.04
bsherwood authored
161 For Ubuntu 7.10, I was unable to install gtkglextmm from source. But at
064bfbb Additional info on building on Linux
bsherwood authored
162 packages.ubuntu.com/source/gtkglextmm, from the older "edgy" distribution get
163 libgtkglextmm1c2a (allow the default package manager to process the download), then
164 libgtkglextmm1-dev.
817b645 Improve listing of dependencies.
bsherwood authored
165
166 To install gtkglextmm:
167 1) Download the bz2 file.
168 2) Unpack the file: tar -xjf gtkglextmm-1.2.0.tar.bz2
169 3) cd to the unpacked directory
170 4) ./configure
171 5) make
172 6) sudo make install
abaacc6 Add automake files to project.
bsherwood authored
173
a6e551d Update configure info concerning Ubuntu 9.04
bsherwood authored
174 II. Configuration
175 It is NOT the case that simply running './configure' is likely to work,
176 because Visual has to be linked to an appropriate Python, so read below.
177
178 There have been significant changes in where 3rd-party software is stored on
2b0b6f8 Minor improvements in the explanation
bsherwood authored
179 Ubuntu 9.04. You probably want to use /usr/bin/python2.6. To configure, do this
180 in a folder parallel to vpython-core2 (or whatever the source folder is named:
a6e551d Update configure info concerning Ubuntu 9.04
bsherwood authored
181
2b0b6f8 Minor improvements in the explanation
bsherwood authored
182 PYTHON=/usr/bin/python2.6 ../vpython-core2/configure --prefix=/usr/local
a6e551d Update configure info concerning Ubuntu 9.04
bsherwood authored
183
184 You will also need to copy vpython-core2/src/gtk2/site-packages.pth to
f884bfd Simplify the configure instructions
bsherwood authored
185 /usr/lib/python2.6/dist-packages to put /usr/lib/python2.6/site-packages
a6e551d Update configure info concerning Ubuntu 9.04
bsherwood authored
186 on the Python search path.
187
07ffa91 Advertise the simple src/gtk2/makefile
bsherwood authored
188 In src/gtk2 there is a simple non-autoconf makefile for Ubuntu 8 as of Nov. 2008.
189 It is unlikely to be kept up to date, but it gives an example of the basic
a6e551d Update configure info concerning Ubuntu 9.04
bsherwood authored
190 elements of what the rather complex autoconf machinery needs to produce.
abaacc6 Add automake files to project.
bsherwood authored
191
192 However, configure also provides a large number of options and is sensitive to
193 several environment variables to properly configure VPython for unique use cases.
194
195 Run `configure --help` for the complete list of options and brief descriptions.
196
197 If you have multiple versions of Python installed, and the one named 'python' that
198 is first on your PATH (identified with `which python`) is not the one you want to
199 build Visual for, specify the correct interpreter by setting the PYTHON
200 environment variable to the desired interpreter's full path.
201
202 If you have multiple versions of GNU G++ installed, and the default is inadequate
203 for VPython, specify the correct one by setting the CXX environment variable to
204 its fully-qualified path.
205
206 You should generally supply the --prefix option to cause Visual to be installed to
207 the same prefix that Python is installed (default is /usr/local).
208
1d1fb9e Add more doc on configure parameters.
bsherwood authored
209 On Linux, do this: which python
210 Make a note of the prefix preceding /bin/python, typically /usr or /usr/local.
211
c628aa3 Added more documentation.
bsherwood authored
212 It is useful to place the visual folder and a folder named "build" at the same level,
74fc087 Update/improve documentation for developers and for those installing on ...
bsherwood authored
213 and configure and make in the build folder by "cd build", then do this:
1d1fb9e Add more doc on configure parameters.
bsherwood authored
214 (a) If prefix is /usr/local, execute
215 ../visual-x.x.x/configure
216 (b) If prefix is something else, and Visual can go into prefix/lib/python/site-packages, execute
217 ../visual-x.x.x/configure --prefix=prefix
218 (c) If you want to use a different version of Python than the one found with "which python",
219 or (b) is not appropriate, specify both the particular Python and where to install Visual:
220 PYTHON=/somewhere1/bin/python ../visual-x.x.x/configure --prefix=/somewhere2
221 If "somewhere1" and "somewhere2" are different, you must also add the "somewhere2"
222 directory to Python's module search path. For details, at www.python.org read section 4.1
223 (Modifying Python's Search Path) in the section Installing Python Modules of the Python
224 on-line documentation.
abaacc6 Add automake files to project.
bsherwood authored
225
c628aa3 Added more documentation.
bsherwood authored
226 Here is a specific example of case (c):
2b0b6f8 Minor improvements in the explanation
bsherwood authored
227 PYTHON=/usr/bin/python2.6 ../vpython-core2/configure --prefix=/usr/local
c628aa3 Added more documentation.
bsherwood authored
228 (This would make sense only if python has /usr/local/lib/site-packages on its
229 search path.)
230
abaacc6 Add automake files to project.
bsherwood authored
231 If you are only building VPython once, you may pass the option
232 --disable-dependancy-tracking to make the build itself go a little faster.
233
234 If your GNOME libraries are installed in a non-standard location (such as
74fc087 Update/improve documentation for developers and for those installing on ...
bsherwood authored
235 /opt/gnome in SUSE), you must set the CPPFLAGS environment variable to
236 -I/other_prefix/include to ensure that you pick up the gtkglarea header files.
abaacc6 Add automake files to project.
bsherwood authored
237
238 Another interesting configuration is to install VPython into a prefix other than
239 the same prefix that Python is installed in. This may be useful to test your
240 VPython programs with different versions of Visual on the same system
241 simultaneously. After choosing an approprate prefix, such as /home/jonathan, run
242 configure as normally but specify the PYTHONPATH environment variable to be
eddd919 change 2.4 to 2.5 in instructions
bsherwood authored
243 [prefix]/lib/python2.5/site-packages, replacing python2.5 with python2.2 if that
74fc087 Update/improve documentation for developers and for those installing on ...
bsherwood authored
244 is your interpreter. You must create this PYTHONPATH directory if it does not
abaacc6 Add automake files to project.
bsherwood authored
245 already exist.
246
247 III. Build
248 Just run 'make'.
249
250 Optionally, you may override the following variables by
251 specifying them in the form VARIABLE=value as arguments to make:
252 LDFLAGS, LIBS, CXXFLAGS, and CPPFLAGS affect options passed to the linker,
253 compiler, and preprocessor, respectively.
254 DESTDIR may be used to prepend DESTDIR to the 'prefix' specified when running
74fc087 Update/improve documentation for developers and for those installing on ...
bsherwood authored
255 configure. This option is mostly useful to binary redistributors of VPython.
abaacc6 Add automake files to project.
bsherwood authored
256
74fc087 Update/improve documentation for developers and for those installing on ...
bsherwood authored
257 The makefiles support the following targets:
abaacc6 Add automake files to project.
bsherwood authored
258 all: (the default) compiles all the required software
259 clean: deletes files created by the compiler
260 distclean: deletes all files created by the configure and make programs. This
261 option is useful if you want to start over from a clean source tree.
262 install: copies all required files in the locations specified by configure
263 install-strip: Performs the 'install' target and strips the final object files.
264 It also makes getting a backtrace impossible on most platforms.
265
266 IV. Install
06124b3 Gave explicit instructions for building gtkgtextmm
bsherwood authored
267 You must have write privileges to the installation directory to proceed. Unless
abaacc6 Add automake files to project.
bsherwood authored
268 you are installing into your home directory, that generally means becoming root
06124b3 Gave explicit instructions for building gtkgtextmm
bsherwood authored
269 with a program like `sudo` or `su`. Just run `sudo make install`.
ae39217 Update detailed instructions for building Windows installer in msys-ming...
bsherwood authored
270
abaacc6 Add automake files to project.
bsherwood authored
271 Alternatively, you may run 'make install-strip' to install a somewhat smaller
272 executable.
273
274 V: Troubleshooting
275 The single most likely cause of an error in the build is that one or more
276 develoment header files could not be found. VPython logs its configuration stage
277 in config.log, and its build stage in src/build.log. If the build fails you
278 must read src/build.log to see what happened. In the event that you cannot
279 solve the problem, compress config.log and src/build.log and include them with
280 your request for assistance to visualpython-users@lists.sourceforge.net.
281
282 But before you do that, it is a good idea to read the archives of the mailing list
283 since someone else has probably worked through your problem already.
284
82d5720 Add debugging info
bsherwood authored
285 From a typescript, the following will print all VPYTHON_NOTEs:
286 env VPYTHON_DEBUG=1 python test.py
287
Something went wrong with that request. Please try again.