From 90825e2392b2d70e43c7a25b8a3752299a933894 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebindings@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- python/pykde/doc/trouble.html | 337 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 python/pykde/doc/trouble.html (limited to 'python/pykde/doc/trouble.html') diff --git a/python/pykde/doc/trouble.html b/python/pykde/doc/trouble.html new file mode 100644 index 00000000..e93592f7 --- /dev/null +++ b/python/pykde/doc/trouble.html @@ -0,0 +1,337 @@ + + + + Troubleshooting + + + + +

+ + + + + +

Python Bindings for KDE (PyKDE-3.16.0)
Prev		Next

Troubleshooting

Introduction

+(There are distribution-specific notes at the end of this page) +

+Before each release, PyKDE is test built against SuSE, Red Hat and Mandrake Linux distributions, +and various versions of Python, Qt and KDE. Even after performing test builds, errors still can +occur with your installation. The most common sources of errors are (roughly in order of occurance): +

Differences in user environments
Differences between distributions (or even between different builds of same version of the same distribution
Bugs - in PyKDE or any of the software it's based on (KDE, Qt, PyQt, sip, or even Python)

Reporting errors -- PLEASE READ!

+The people on the PyKDE mailing list are knowledgeable about Python, PyQt,and PyKDE and are +genuinely helpful. You shouldn't hesitate to post a question or problem there (you may hear +"RTFM" occasionally, but not often). Chances are that someone using your distribution is already +posting to the list. +

+The most important thing you can do when reporting an installation error is to include the +configure.py output with your question, including the error message at the point of failure. +All configure.py messages write to stdout, so if you can't cut and paste the output, you can do: +

+ + + + +

+    python configure.py > output.txt
+

+to capture the output and attach the file to your post. In many cases, if you don't include +this info, the first response to your question will be to ask for the configure.py output. Including +it with your original post will save several hours or days in the process of obtaining an answer. +

+Bug reports are a vital part of any software development process. We generally try to provide +an immediate fix or work-around for problems reported, and then incorporate the fix into +future releases. Bug reports are always welcome (and always embarrassing). +

+If you are reporting PyKDE run-time errors (not install errors), there's no need to include +the configure.py output, but at a minimum you should indicate what PyKDE version the error +occurred with and provide a small code sample that reproduces the error. +

If you perform repairs ...

+If you edit any of the sip files to repair bugs or modify PyKDE, you must re-run +configure.py. configure.py includes code that generates the actual C++ code that compiles to PyKDE. +If you don't re-run configure.py, changes to the sip files will have no effect. +

configure.py and make errors

"Can't find a file or directory": +configure.py first checks to make sure that it can locate and access all of the components PyKDE +depends on. If the directories or files aren't where configure.py thinks they should be, an error +will result and configure.py will exit. Usually these kinds of problems can be solved by adding +command line switches when running configure.py - see the next page for +the available command line options +
"Can't write ..." or "Can't create ...": +build.py creates a number of directories and generates Makefiles and a lot of C++ code +(customized for your system). If the user running build.py doesn't have write access to +the directories where PyKDE sources were installed, the build will fail. You need to either +obtain write access, relocate PyKDE someplace where you have write access or (worst choice) +build PyKDE as root. +
"Can't remove or create directory": +This happens rarely, but is a quirk of the PyKDE build process. PyKDE will build and make +as an unprivileged user BUT if you did a build of PyKDE previously as root and then attempt +to build PyKDE again as a user, the build will fail. The reason is that configure.py creates a +number of directories and a lot of files. The next time configure.py runs, it will try to delete +these directories and files before re-creating them. If the original directories and files +were owned by root, a user will be unable to delete them and configure.py will fail if run as +a user in that case. +
"Can't find PyQt sip files": +You did install them, right? If you build PyQt from sources, the sip files will be there +somewhere (by default, PyQt installs the PyQt sip files in /usr/share/PyQt if built from +source). When you find them, you can tell configure.py where they are with a switch (see +next page). If you installed PyQt from RPMs (either downloaded or +from your distribution), the sip files are usually in a "devel" RPM for PyQt, which also needs +to be installed if you want to build PyKDE from sources. +
Code generation errors: +The PyKDE sources are mostly "sip" files which describe the interface to KDE's C++ libraries +to the sip code generator. These files should be error free. If a sip or code generation error occurs, +please report it to the PyKDE mailing list at +PyKDE@mats.imk.fraunhofer.de Subscribe to the list +here +
Compile errors: +PyKDE should not experience any compile errors. Currently sip 4.0 based compiles will +generate a number of warnings - these can be safely ignored. If errors occur, please report them +to the PyKDE mailing list at PyKDE@mats.imk.fraunhofer.de . +Subscribe to the list here +

Compile-time errors

+PyKDE takes a long time to compile on some hardware, however no single module should take more than 25-30 +minutes on any but the slowest hardware. Some gcc versions (for example gcc 4.0.1 on SuSE 10) will hang +if PyKDE C++ files have been generated in "concatenated" mode (see Installation and Switches pages for +more info). If you are using concatenated mode (each module consists of a single large file, instead of +many small files) and PyKDE's compilation hangs, re-run configure.py with the -i switch, then re-run make. +

+PyKDE attempts to identify gcc versions that have problems and select the correct mode automatically. +

Run-time errors

importTest.py errors

+All that importTest.py does is try to import each of the PyKDE modules. The most common error that +occurs when running importTest.py is that an unresolved symbol in one of the modules prevents the +module from loading. This can occur because not all KDE library versions contain all of the "official" KDE +classes and members. Although it doesn't occur often, 1 missing method (out of over 10,000) will +prevent a module from loading, and also prevent other modules that depend on the failing module +from loading. The error message will normally print a "mangled" version of the missing method's name: +

+ + + + +

+    > ImportError: /usr/lib/python2.2/site-packages/libkdecorecmodule.so:
+    > undefined symbol: _ZNK10KAboutData18copyrightStatementEv
+

+You can decipher the mangled name to a class and method (in the example above, +KAboutData::copyrightStatement) by running: +

+ + + + +

+    c++filt <symbolname>
+    
+    for example:
+    
+    c++filt _ZNK10KAboutData18copyrightStatementEv
+

+If you can locate the sip file for the class, you can comment out ("//") the missing method, and recompile +(including re-running configure.py. If you can't solve the problem (and even if you do) you should +report it on the PyKDE mailing list at +PyKDE@mats.imk.fraunhofer.de . Subscribe to the list +

+here +

Other run-time errors

+At present only the most likely failure modes of PyKDE are tested (contributions of tests/test code +are greatly appreciated). Nearly all of PyKDE is completely machine generated from the KDE h files, +so coding errors are rare but they do happen. PyKDE also uses some classes and methods differently +because it's running from Python and not C++. If you suspect an error, please double-check your +code and review the PyKDE docs to be sure the argument lists and expected return types are what you +thought they were. If the problem persists, report it to the PyKDE mailing list at + PyKDE@mats.imk.fraunhofer.de . Subscribe to the list +here. When reporting errors to the +list, it's always helpful if you provide: +

+the version of PyKDE you're using +
+ a small sample of code that produces the problem. +

+It's not particularly important whether the error is a PyKDE error or a user error (although +I prefer seeing user errors rather than my own). +

Distribution-specific Notes

SuSE 8.0/8.1

+During testing of PyKDE for KDE 3.x.x on SuSE 8.0 and 8.1 I +ran into problems with the kjs module insisting on linking to +the KDE2 version of libkjs.so instead of the KDE3. The lib +name/version is the same in both cases, but the libs aren't +compatible. The only solution I found was to: +

+1.Edit (as root) /etc/ld.so.conf from this: +

+ + + + +

+    /opt/kde
+    /opt/kde2
+    /opt/kde3
+

+ to this: +

+ + + + +

+    /opt/kde3
+    /opt/kde
+    /opt/kde2
+

+2. Run (as root) ldconfig +

+3. Re-link. You can save having to rebuild PyKDE and recompile +by simply going into the PyKDE-3.x.x/kjs directory and deleteing +kjshuge.o (or any *.o in the directory) and then rerunning make +and make install (this forces a recompile/relink of the kjs module +only, which is very fast) Don't run configure.py before trying this, +or everything will recompile. +

+Alternatively, if you don't plan on using kjs, you can simply +ignore the fact that it's mis-linked - it won't affect any +other module. +

SuSE 8.2/9.0

+Some (but by no means all) versions of the KDE rpms for recent SuSE distributions appear +to have been built with a different version of kfileshare.h than what they ship with. This +version is also in disagreement with the "official" KDE version (as found in the kdelib +source files on kde.org, for example). The "incorrect" versions use a setShared(...) method +with a different argument list that doesn't match the h files. +

+To fix this problem, all versions of the setShared method should be commented out in +kfileshare.sip. +

Mandrake 9.1

(rpm install - PyKDE-3.8, not 3.11 so far)

+Some people have had trouble with the Mandrake 9.1 rpms/KDE libs. All +distributions modify KDE in some way and where feasible, PyKDE is +set up to build with the least common denominator. +

+The following exchange is from the PyKDE mailing list. The reply is +from Simon Edwards: +

+ + + + +

+    > I'm trying to setup PyKDE on my Mandrake 9.1/python 2.2 box but so far I
+
+    > ImportError: /usr/lib/python2.2/site-packages/libkdecorecmodule.so:
+    > undefined symbol: _ZNK10KAboutData18copyrightStatementEv
+
+    Let me guess. You are using the original KDE version that came with Mandrake
+    9.1. :) yeah, there is a problem and the PyKDE rpms for mandrake don't work
+    with that version.
+
+    What you can do is update your KDE to 3.1.4. That should work. I'm using 3.1.2
+    here. You can go here:
+
+        http://plf.zarb.org/~nanardon/urpmiweb.php
+
+    and follow the directions and remember to select 'Texstar'. Now you will be
+    able to upgrade KDE using the Mandrake Install tool. Open up the Mandrake
+    Control Center and go to Install Software, do a search on "kde" and you
+    should get a big long list of KDE packages. Select the 3.1.4-tex2 ones and
+    when you are ready hit 'install'. and wait, and wait. :-)
+

Mandrake 10.x

+Some people have had trouble compiling with Mandrake 10.x. Mandrake provides a few "non-standard" +h files. This only affects 3 or 4 methods, but is enough to prevent PyKDE from building. PyKDE 4.0 +includes patches that should eliminate this problem. +

+ + + + + + + + + + + +

Prev	Home	Next
Installation		build.py Options

+ + + -- cgit v1.2.1