10.1. Compiling Regina |
- 10.1.1.
The ./configure script complains that it
cannot find libgmp, libxml2,
libjpeg or some other library.
- 10.1.2.
The ./configure script complains that it
cannot find the X includes.
- 10.1.3.
The ./configure script complains that it
cannot find the important program mcopidl.
- 10.1.4.
The compiler complains that it cannot find
-lart_lgpl_2, -lselinux or
-l... for some other library.
- 10.1.5.
The compiler breaks somewhere beneath
regina-version/kdeui/src
with complaints of an undeclared identifier.
| |
| 10.1.1. |
The ./configure script complains that it
cannot find libgmp, libxml2,
libjpeg or some other library.
|
|
An error such as this means that you are probably missing the
development files for a library that you need. If the warning
is regarding libfoo, look
for a package such as foo-devel,
libfoo-devel, foo-dev or
some similar variation that you can install. These development
packages contain headers and other files that the compiler needs
in order to link against the corresponding library.
For the three examples above, Debian users would need to install
the packages libgmp3-dev,
libxml2-dev and libjpeg62-dev.
Red Hat /
Fedora users would need to install the packages
gmp-devel, libxml2-devel
and libjpeg-devel.
If you know you have the appropriate library development files
installed and you are still seeing this error, it might be that
the ./configure script simply cannot find them.
In particular, if the library has been installed in a non-standard
location, you might need to explicitly pass its location to the
./configure script. As an example, if a
library is installed beneath /usr/local
with headers in /usr/local/include and
the library itself in /usr/local/lib, you
can pass the following options:
example:~/source/regina> ./configure
--with-extra-includes=/usr/local/include
--with-extra-libs=/usr/local/lib
checking build system type... i686-pc-linux-gnu
checking host system type... i686-pc-linux-gnu
...
Note that some libraries come with their own custom
./configure options. For instance, the
location of the Qt installation is specified using the option
--with-qt-dir, and the location of the
libxml2 installation is specified using the
option --with-xml-prefix. Run
./configure --help for details of all
available options.
Finally, please visit the online page for
building
Regina on different distributions, which may be able to
give ./configure options tailored for your
specific type of machine.
|
| 10.1.2. |
The ./configure script complains that it
cannot find the X includes.
|
|
You will need to install the X development files on your system,
which are almost certainly available as a package in your
GNU/Linux distribution. As an example, Debian users should install
the package xlibs-dev, Red Hat Enterprise 3 users
should install XFree86-devel and Fedora Core 2
users should install xorg-x11-devel.
Be aware that you will also need the Qt and KDE development
files. For Debian users these are in the packages
libqt3-mt-dev and
kdelibs4-dev, and for Red Hat /
Fedora users
these are in the packages qt-devel and
kdelibs-devel.
|
| 10.1.3. |
The ./configure script complains that it
cannot find the important program mcopidl.
|
|
You are missing the aRts development
files. Hopefully your distribution will insist on these being
installed alongside the KDE development files, but some
distributions seem to have unhappily weak package dependencies.
To install the missing aRts
development files, look for a package such as
arts-devel, libarts-devel,
libarts-dev or some similar name.
For instance, Debian users should install
libarts1-dev, and Red Hat /
Fedora users should
install arts-devel.
|
| 10.1.4. |
The compiler complains that it cannot find
-lart_lgpl_2, -lselinux or
-l... for some other library.
|
|
This is similar to the
./configure
problem described earlier regarding missing libraries,
except that the problem wasn't noticed at
configuration time. Again you are probably missing the
development files for a library that you need. If the error
is that the compiler cannot find -lfoo, look
for a package such as foo-devel,
libfoo-devel, foo-dev or
some similar variation that you can install.
As an example, some Fedora Core systems will give the compile error
"/usr/bin/ld: cannot find -lselinux", which is
fixed by installing the package libselinux-devel.
Similarly, a failure to find -lart_lgpl_2 on
a Red Hat Enterprise system can be fixed by installing the package
libart_lgpl-devel.
|
| 10.1.5. |
The compiler breaks somewhere beneath
regina-version/kdeui/src
with complaints of an undeclared identifier.
|
|
Look at the error message to see which particular identifier has
not been declared. An example of such an error is reproduced
below, where the undeclared identifier in this case is
adjustColumn.
nanglestructureui.cpp: In constructor `NAngleStructureUI::NAngleStruct...
nanglestructureui.cpp:84: error: `adjustColumn' undeclared (first use ...
nanglestructureui.cpp:84: error: (Each undeclared identifier is report...
make[4]: *** [nanglestructureui.lo] Error 1
make[4]: Leaving directory `/home/bab/source/regina-4.0/kdeui/src/part...
If the undeclared identifier is
adjustColumn or
SH_Table_GridLineColor,
you almost certainly have a Qt version that is too old. Regina
requires Qt version 3.2 or higher; trying to compile Regina
against Qt 3.1 will result in errors such as these.
|
10.2. Running Regina |
- 10.2.1.
Regina refuses to open any topology data files, claiming that an
appropriate topology data component could not be found.
- 10.2.2.
I see no way to create a new topology data file. There is no
New Topology Data
menu item and no correponding toolbar button.
- 10.2.3.
I cannot edit a particular packet. I can view it but I can't change
anything.
- 10.2.4.
I cannot open the Regina handbook. I try
selecting Regina Handbook from the
Help menu but I get an error message.
- 10.2.5.
The program complains that Python scripting has been disabled.
- 10.2.6.
While working with a Python object I receive a
TypeError with the message
"bad argument type for built-in operation".
I know the object is valid since I've used it earlier without problems.
- 10.2.7.
While calling a Python function I receive a
Boost.Python.ArgumentError with the message
"Python argument types did not match C++ signature". I'm
fairly sure I'm passing the right arguments.
| |
| 10.2.1. |
Regina refuses to open any topology data files, claiming that an
appropriate topology data component could not be found.
|
|
It is critical that Regina be installed in the same location as
all other KDE applications on your system. For instance, if
KDE is installed beneath /opt/kde3 then
Regina must be installed there also.
Errors such as this occur when Regina has not been installed
in the same location as KDE, and thus KDE cannot find one or
more of its components.
The location in which Regina is installed is controlled at
compile-time by passing a --prefix option to the
./configure script. The
./configure script will generally guess the
correct location itself, so in most cases you
should not be passing your own --prefix at all.
However, if you are seeing this problem, working out the correct
--prefix and then rebuilding and reinstalling
Regina will almost certainly fix it.
To find which prefix you should be using,
search for the kde-config program on your
system. Running kde-config --prefix will
report the prefix that was used for your KDE installation. You
must then pass this same prefix to ./configure.
For instance, if kde-config --prefix
reports /usr then you should
start your Regina build with
./configure --prefix=/usr as illustrated
below.
example:~/source/regina> kde-config --prefix
/usr
example:~/source/regina> ./configure --prefix=/usr
checking build system type... i686-pc-linux-gnu
checking host system type... i686-pc-linux-gnu
...
|
| 10.2.2. |
I see no way to create a new topology data file. There is no
menu item and no correponding toolbar button.
|
|
These symptoms are caused by the same --prefix
issue described in the previous
question, and can be fixed the same way.
|
| 10.2.3. |
I cannot edit a particular packet. I can view it but I can't change
anything.
|
|
If a packet has children that need their parent
to remain constant, it will
become uneditable. An example is a triangulation that has a normal
surface list as a child. The normal surface list stores coordinates
based upon the triangulation that created it, so the triangulation
must remain constant or else the coordinates will become invalid.
In such a situation you can try cloning
the packet without its subtree (->). The clone will have no children to worry about
and so should be editable. Alternatively you could delete the child
packet that is refusing to allow its parent to change.
Note that if a packet cannot be edited because of its children,
it will be marked with a small padlock in the packet tree. This is
illustrated below for the figure eight knot complement.
|
| 10.2.4. |
I cannot open the Regina handbook. I try
selecting Regina Handbook from the
Help menu but I get an error message.
|
|
There are two common causes for this problem, each outlined below.
However, if all else fails you can always download
the handbook in HTML format directly from the
Regina
download site, or you can simply
read it online.
If you get an error such as "Could not launch the KDE Help
Center" or "Could not find khelpcenter executable",
you probably do not have the KDE Help Center installed. Search your
GNU/Linux distribution for the kdebase package
(some distributions call this kdebase3,
kdebase-progs or kdebase-unified).
Hopefully installing this package will make your problem go away.
If you get an error such as "There is no documentation available
for /regina/index.html", you probably have the Regina
handbook installed in the wrong location.
If you installed Regina from a ready-made package, please contact
the package maintainer — the package has been built incorrectly
and needs to be fixed. For most of the ready-made packages, you
can reach the package maintainer by mailing <regina-user@lists.sourceforge.net>.
If you built Regina yourself from sources, you need to pass an
extra argument to the ./configure script.
Try to find which directory on your system contains the KDE
user manuals; typically this is something like
/usr/share/doc/kde or
/usr/share/doc/kde/HTML. This directory
should have an en/ subdirectory, and beneath
that a subdirectory for each application (such as
en/kicker, en/kate and
so on).
Once you have found this directory, pass it as a
kde_htmldir argument to the
./configure script (note that this
option does not begin with --). An example
for a Debian system is given below.
example:~/source/regina> ./configure kde_htmldir=/usr/share/doc/kde/HTML
checking build system type... i686-pc-linux-gnu
checking host system type... i686-pc-linux-gnu
...
|
| 10.2.5. |
The program complains that Python scripting has been disabled.
|
|
This means that Regina was not built with Python support
enabled. You will need to rebuild Regina from sources –
instructions for doing this are provided in the file
README.txt in the Regina source
distribution.
When running ./configure (the first step of
building Regina), watch the output carefully. It will tell you
whether it plans to build the Python interface, and if not it
should give you a clear reason why.
example:~/source/regina> ./configure
...
... (lots of tests)
...
configure: WARNING: A working boost.python installation is
unavailable; the Python interface will not be built.
...
... (more tests)
...
checking whether to build the calculation engine library... yes
checking whether to build the KDE user interface... yes
checking whether to build the Python interface... no
checking whether to build command-line utilities... yes
checking whether to build MPI-enabled utilities... yes
checking whether to build the test suite... yes
checking whether to build calculation engine docs... yes
configure: creating ./config.status
config.status: creating Makefile
config.status: creating admin/Makefile
...
... (lots more Makefiles)
...
example:~/source/regina>
The most common cause for Python support being disabled
is that no usable boost.python installation could be found at
compile time (as illustrated above). Make sure you have
boost.python installed as described on the system
requirements page.
If your boost.python is installed in a
non-standard location you may need to pass this location to the
./configure script using options
--with-extra-includes and
--with-extra-libs.
example:~/source/regina> ./configure
--with-extra-includes=/usr/local/include
--with-extra-libs=/usr/local/lib
checking build system type... i686-pc-linux-gnu
checking host system type... i686-pc-linux-gnu
...
Note that boost.python also requires the standard Python headers to
be installed; again see the system
requirements page for details.
If none of these suggestions help, please mail <regina-user@lists.sourceforge.net> for
assistance, including your config.log
if possible to help diagnose the problem.
|
| 10.2.6. |
While working with a Python object I receive a
TypeError with the message
"bad argument type for built-in operation".
I know the object is valid since I've used it earlier without problems.
|
|
You may have run into an unusual boost.python issue regarding
ownership semantics. If you have been rearranging the packet tree
using NPacket.insertChildFirst(),
NPacket.insertChildLast() or
NPacket.insertChildAfter() then this is
particularly likely.
See the Python caveats
documentation for a description of this problem and how to
work around it.
|
| 10.2.7. |
While calling a Python function I receive a
Boost.Python.ArgumentError with the message
"Python argument types did not match C++ signature". I'm
fairly sure I'm passing the right arguments.
|
|
You may have run into the same unusual ownership issue with
boost.python discussed in the
previous question.
Again, if you have been rearranging the packet tree
using NPacket.insertChildFirst(),
NPacket.insertChildLast() or
NPacket.insertChildAfter() then this is
particularly likely.
See the Python caveats
documentation for a description of this problem and how to
work around it.
On the other hand, it may just be that you are calling the
function incorrectly. You might wish to check the
calculation engine documentation,
which describes all of the available function calls and what
arguments they should take.
|
10.3. Miscellaneous |
- 10.3.1.
What is the test suite, and how do I run it?
- 10.3.2.
Something else not described in this list has gone
wrong. Perhaps something crashed. Maybe the program gave the wrong
answer. Or it could be just a little too slow.
| |
| 10.3.1. |
What is the test suite, and how do I run it?
|
|
Sometimes, building an application on significantly different
hardware or against different versions of helper libraries can lead
to unforseen bugs that do not appear on the developer's machine(s).
To help guard against such problems, Regina ships with a test
suite. The test suite uses Regina to perform a variety of
different computations that isolate different portions of
Regina's mathematical code, and it verifies that Regina gets
the answers correct.
The test suite comes with the Regina source distribution, and it
assumes that you are building Regina yourself. Note that the
test suite requires CppUnit to be
installed, as described on the system
requirements page on the Regina website.
To build and run the test suite, simply move into the main source
directory and type make check. After the
test suite has been compiled, you should see the individual tests
being run as illustrated below.
example:~/source/regina> make check
Making check in engine
make[1]: Entering directory `/home/bab/source/regina/engine'
...
... (compiling the test suite)
...
make[3]: Entering directory `/home/bab/source/regina/testsuite'
Regina calculation engine test suite
NIndexedArrayTest.basicChecks... ok.
NIndexedArrayTest.constructors... ok.
NIndexedArrayTest.swap... ok.
NIndexedArrayTest.inserts... ok.
NIndexedArrayTest.erasures... ok.
...
... (running lots more tests)
...
NAngleStructureListTest.loopC2... ok.
NCensusTest.rawCounts... ok.
NCensusTest.rawCountsPrimeMinimalOr... ok.
NCensusTest.rawCountsPrimeMinimalNor... ok.
NFacePairingTest.rawCounts... ok.
OK (54 tests)
PASS: regtestsuite
==================
All 1 tests passed
==================
make[3]: Leaving directory `/home/bab/source/regina/testsuite'
...
... (more output from make)
...
make[1]: Leaving directory `/home/bab/source/regina'
example:~/source/regina>
We see from the output above that the test suite ran as expected
and that all tests were passed.
|
| 10.3.2. |
Something else not described in this list has gone
wrong. Perhaps something crashed. Maybe the program gave the wrong
answer. Or it could be just a little too slow.
|
|
Please! - mail me at <bab@debian.org> and let me know. Or even better,
use the SourceForge services
such as the bug tracking system and mailing lists so that the
problem you report is publicly archived.
This program is permanently in development. There is a very
long TODO list, and chances are your problem is on it. And
then again chances are it's not. So please let me know so I
am sure to know what needs to be fixed/improved.
|
