1For several years the Python world has been in a state of transition from 2version 2.x to 3.x. Much code still exists for Python2 in the form of 3applications, modules, and packages and will likely be supported for some 4time to come. Python3 is gaining acceptance, especially with new 5development and many modules and packages are now available for Python3. 6 7The Python developers have taken care to ensure that Python2 and Python3 8and their respective modules and packages can be installed concurrently. 9The steps below take advantage of this feature to install Hamlib.py modules 10for both Python versions. Complete installation of each Python version 11including their respective development files are required for successful 12generation of the bindings by SWIG. 13 14At this time the GNU Autotools do not offer a clean method of building SWIG 15bindings for multiple versions of Python. Some hacks can be found on the 16Web but until a clean native solution is offered the steps in this document 17should prove adequate. With the wealth of Python2 programs, modules, and 18packages still in use, it isn't likely to disappear from distributions 19anytime soon. Python3 is becoming more popular for new development with a 20complete standard library and many modules and packages being ported over 21and available. It's time that we offer a means to generate bindings for 22either version. This document will provide the steps for doing so. 23 24NOTE: Developers and testers building from a Git clone/checkout will need 25to bootstrap the build system by running the (appropriately named) 'bootstrap' 26script. Source releases and source daily snapshots already have this step 27completed. 28 29NOTE: The commands assume an out of tree build in a sibling directory to 30the main source directory. Adjust your paths accordingly. Adjust your 31--prefix option as needed (installation to the user's home directory is 32shown to avoid root privileges). 33 34Assuming that Python2 is the default installed Python interpreter, build 35its bindings first: 36 37 ../hamlib/configure --with-python-binding --prefix=$HOME/local 38 make 39 make install 40 41NOTE: Over time Python3 will become the default Python interpreter on most 42distributions and the extra step will be needed for Python2 as detailed below. 43 44At this point the Hamlib binaries, development files, and Python2 bindings 45will be installed to their customary locations under $HOME/local. 46 47Examination of the configure script's output will confirm that Python2 is 48found and used as this extract shows: 49 50checking whether to build python binding and demo... yes 51checking for python... /usr/bin/python 52checking for a version of Python >= '2.1.0'... yes 53checking for the distutils Python package... yes 54checking for Python include path... -I/usr/include/python2.7 55checking for Python library path... -L/usr/lib64 -lpython2.7 56checking for Python site-packages path... /usr/lib64/python2.7/site-packages 57checking python extra libraries... -lpthread -ldl -lutil -lm 58checking python extra linking flags... -Xlinker -export-dynamic 59checking consistency of all components of python development environment... yes 60checking whether /usr/bin/python version is >= 2.1... yes 61checking for /usr/bin/python version... 2.7 62checking for /usr/bin/python platform... linux2 63checking for /usr/bin/python script directory... ${prefix}/lib64/python2.7/site-packages 64checking for /usr/bin/python extension module directory... ${exec_prefix}/lib64/python2.7/site-packages 65 66At this point the file pytest.py in the source bindings directory may be 67run as a test. If an error is given that the Hamlib module cannot be 68found, see below. 69 70The next step is to configure and build for Python3: 71 72 ../hamlib/configure --with-python-binding PYTHON_VERSION='3.6' --prefix=$HOME/local 73 74If that doesn't work try: 75 76 ../hamlib/configure --with-python-binding PYTHON=$(which python3) --prefix=$HOME/local 77 78then do the build: 79 80 cd bindings 81 make 82 83NOTE: By changing the current directory to 'bindings', only the new Python3 84module will be compiled, which speeds things up considerably. 85 86Here the PYTHON_VERSION environment variable is set to the Major.minor version 87of Python we wish to build against. The build system should be able to set 88everything correctly from this environment variable. If not, try the second 89example line which sets the PYTHON environment variable to the first python3 90executable found in the path (python3 may be a symbolic link, which is fine). 91This may be unwanted behavior if multiple versions of Python are installed so 92a specific version with the full path may also be provided. 93 94Python3 was found as shown in this configure output extract: 95 96checking whether to build python binding and demo... yes 97checking for python3.6... /usr/bin/python3.6 98checking for a version of Python >= '2.1.0'... yes 99checking for the distutils Python package... yes 100checking for Python include path... -I/usr/include/python3.6m 101checking for Python library path... -L/usr/lib64 -lpython3.6m 102checking for Python site-packages path... /usr/lib64/python3.6/site-packages 103checking python extra libraries... -lpthread -ldl -lutil -lm 104checking python extra linking flags... -Xlinker -export-dynamic 105checking consistency of all components of python development environment... yes 106checking whether /usr/bin/python3.6 version is >= 2.1... yes 107checking for /usr/bin/python3.6 version... 3.6 108checking for /usr/bin/python3.6 platform... linux 109checking for /usr/bin/python3.6 script directory... ${prefix}/lib64/python3.6/site-packages 110checking for /usr/bin/python3.6 extension module directory... ${exec_prefix}/lib64/python3.6/site-packages 111 112Since all the Makefiles were regenerated by the second run of configure, 113hamlib will be compiled again. 114 115Next install only the Python3 bindings (still in 'bindings' as the current 116directory): 117 118 make install 119 120In this case, only the generated files in 'bindings' will be installed 121which will be the new Python3 bindings. 122 123Test that the Hamlib Python3 bindings are found by running the 124bindings/py3test.py script. 125 126At this point working bindings are installed and have been tested. 127 128Running 'make uninstall' will only remove the version of the bindings that 129was last configured. To uninstall the other version the respective options 130will need to be passed to 'configure' and 'make uninstall' run again. 131 132What to do if Python complains the module cannot be found. 133 134There are various ways that a specific path can be provided to Python. 135Perhaps the easiest is to provide an environment variable to your script. 136 137Since Python will not have $HOME/local/... in its search path, here is an 138example: 139 140 $ py3test.py 141 Traceback (most recent call last): 142 File "./py3test.py", line 9, in <module> 143 import Hamlib 144 ModuleNotFoundError: No module named 'Hamlib' 145 146This isn't good! Let's set an environment variable for the running script: 147 148 PYTHONPATH=$HOME/local/lib64/python3.6/site-packages:$PYTHONPATH ./py3test.py 149 150Success! 151 152Like the standard PATH environment variable PYTHONPATH can contain multiple 153paths separated by colons. In this case, if PYTHONPATH was already set the 154new path is prepended to its prior setting. 155 156While setting the environment variable is good for a one-off run, a more 157permanent solution can be achieved by placing a file that ends in .pth in a 158directory that Python will process when starting. The special place is: 159 160 ~/.local/lib64/python3.6/site-packages 161 162A .pth file must be set for each major.minor version of Python. Here is an 163example for Python 2.7: 164 165 $HOME/.local/lib64/python2.7/site-packages/home.pth 166 167Its content is simple: 168 169 /home/username/local/lib64/python2.7/site-packages 170 171(These examples are from a Slackware box which installs Python modules into 172the 'lib64' directory. Other distributions may simply use 'lib' or another 173name.) 174 175To verify the path, start the Python interpreter in interactive mode, 176import the sys module, and check the value of sys.path. It will show a 177number of paths in the list including the ones above and the directory the 178interpreter was started from and various system directories. 179 180Far more information than this is available in the relevant Python 181documentation, but this should get your scripts working. 182 183Removing (uninstalling) the bindings can be done from the 'bindings' 184directory. Just be sure that 'configure' is run with the options for either 185Python2 or Python3 first so that 'bindings/Makefile' will generated for the 186version to be removed. 187 188As always, feedback is welcome: 189 190 Hamlib Developers <hamlib-developer@lists.sourceforge.net> 191 19273, Nate, N0NB 193