Python: Building and debugging

From ILWIS
Jump to: navigation, search
Main Page Arrow.png Software development Arrow.png Building and debugging

Building and debugging
Building and debugging the python extension

Installing the prerequisites: Python 3, SWIG and NSIS
Note: NSIS is only required for building a distributable installer package.

Mar.jpg

SWIG does not require an actual installation, it only needs to be downloaded and unzipped in a folder of your choice.
E.g. unzip in C:\Program Files (x86)\swigwin\


Building and debugging the python extension
Configuring the pythonapi project in QtCreator for building and debugging the python extension

1. Set the pythonapi.pro as the Active Project by:
Mar.jpg

  • Right-click on the python api in the "Projects" sidebar, and
  • Select Set "pythonapi" as Active Project
2. In the Build view of the pythonapi project configuration
Mar.jpg

  • Press and hold <Ctrl>+5 and then click Desktop -> Build
  • add the following custom build step (Build Steps -> Add Build Step -> Custom Process Step) and
  • move it up to be the first build step before qmake and make
Command: C:\Program Files (x86)\swigwin\swig.exe
Arguments: -python -c++ ilwisobjects.i (pay attention to spaces)
Working directory:  %{sourceDir}\pythonapi


Building the python extension

Mar.jpg

  • Right-click the pythonapi project; click "Build"

The extension will be built for the specific version of Python that was installed (e.g. Python 3.3). To be clear: this extension will not work on older (e.g. Python 3.2) or newer (e.g. Python 3.4) versions. To support multiple Python versions (3.3, 3.4, 3.5, 3.6), you must build the extension several times, one for each version. The pythonapi project will look in two locations for installed Python versions:

  1. The "external" folder of the ilwis project (e.g. D:\ilwis\external\Python34)
  2. The root of the C:\ drive (e.g. C:\Python34)

No other folders are searched. To change this, edit the pythonapi.pro file .
When multiple Python versions are available on the system, the newest one will be used. To change this or fix to a specific python version, edit the pythonapi.pro file.

Debugging the python extension within QtCreator

Mar.jpg

  • 1. Create a folder called "ilwis" in folder C:\Python3x\Lib\site-packages
  • 2. Manually copy the files ilwisobjects.py and _ilwisobjects.pyd from folder output\win32[debug or release]\bin\extensions\pythonapi to the "ilwis" folder from step 1
  • 3. In folder "ilwis" from step 1, rename file "ilwisobjects.py" to "__init__.py" (note the double underscores)
  • 4. In folder "ilwis" from step 1, create a textfile named ilwislocation.config (without extension .txt), with the following two lines as its content (the second line is the path of the win32debug output folder, ending with a slash /):
[Paths]
ilwisDir=D:/ilwis/output/win32debug/bin/
  • 5. Start IDLE (the editor that comes with Python) 6. In QtCreator, go to Debug -> Start Debugging -> Attach to Running Application...
  • 7. In "Filter" type python
  • 8. Select the lowest pythonw.exe process, and click "Attach to Process"
  • 9. Now use IDLE to execute python code that will trigger the ilwis extension, e.g. "import ilwis"


Notes:

Close IDLE before re-building ilwis projects with QtCreator (otherwise the dll files can't be written)
After a rebuild of the pythonapi project, it is required to repeat steps 2 and 3 (overwrite the files in C:\Python3x\Lib\site-packages\ilwis )


Creating an NSIS installer for the python extension
Configuring the pythonapi project in QtCreator for building an NSIS installer

Mar.jpg

  • 1. In the Run view of your pythonapi project configuration (<Ctrl>+5, then click Desktop->Run) add a make step (Deployment -> Add Deploy Step -> Custom Process Step) with the following parameters:
Command: C:\Program Files (x86)\NSIS\makensis.exe
Arguments: /V4 installerPy.nsi
Working directory: depending on if you are working on a debug or a release build:
  • click "Browse..." and navigate to the output\win32debug or output\win32release folder of the ilwis binaries, and then
  • click "Select Folder".
The working directory will be e.g. D:\ilwis\output\win32release
  • 2. Edit file installerPy.nsi. Make the following changes:
  • 2a. The name of the output file (variable OutFile), e.g. "ILWISObjects-beta3.0-forPython3.4-32bit.exe"
  • 2b. The registry location that the installer will use to detect the path where this exact version of Python is installed.
  • 2c. All other texts that contain the version number

Building an NSIS installer for the python extension

Mar.jpg

  • Right-click the pythonapi project, click "Deploy"

It is recommended to only build installers of "release" binaries.
"debug" binaries can't be deployed to other computers than your own.
Note that if you actually try the installer and perform the installation on your own computer, folder C:\Python3x\Lib\site-packages\ilwis (and especially file ilwislocation.config) will be overwritten. To be able to debug again, you must edit the location in this file (see step 4 under "Debugging the python extension within QtCreator").