pypi.org<\/h2>\n
pypi.org<\/a> is an official repository of software for the Python programming language. It includes libraries we want to use in our projects, which are not shipped by default with Python.<\/p>\n <\/p>\n Our goal is to package an application written in Python (targetting Python3) as a .deb package for Raspbian (which is, all things considered, really equivalent to Debian). <\/p>\n Our application has dependencies on several Python libraries. <\/p>\n For instance, we would like to use the requests<\/strong><\/a> <\/strong>library. The requests library itself depends on other libraries, e.g. chardet, urllib3, etc.<\/p>\n Manually managing these dependencies and manually shipping the required library code is inherently impractical.<\/p>\n Python has it\u2019s own package \/ dependency management system, called pip<\/strong><\/p>\n pip allows you to install python libraries and applications, so that your own code can use these libraries.<\/p>\n Here there are two problems:<\/p>\n Therefore we need a solution. <\/p>\n virtualenv will allow us to create virtual environments for Python. <\/p>\n In these virtual environments we have:<\/p>\n Install virtualenv (as part of dh-virtualenv, which we will get to in a little while) by doing:<\/p>\n sudo apt install dh-virtualenv<\/p>\n<\/blockquote>\n As requests is already installed system-wide on my test box, we will use a different package as an example. randstr<\/a> will allow you to generate a random string.<\/p>\n Check if randstr <\/strong>is installed system-wide:<\/p>\n pip3 show randstr<\/p>\n<\/blockquote>\n This should return nothing. Indicating that this package is not installed systemwide:<\/p>\n Now we will create a virtual environment. The virtual environment folder does NOT have to live inside your code folder, but it can. You should ignore it in GIT.<\/p>\n let\u2019s say we have a directory \/home\/pi\/tutorial <\/p>\n Change into this directory, and create a new environment folder env:<\/p>\n cd \/home\/pi\/tutorial<\/p>\n which python3<\/p>\n virtualenv -p \/usr\/bin\/python3 env<\/p>\n<\/blockquote>\n Note: you should specify the Python interpreter if you want Python 3, as otherwise Python 2 will be used. I am using Python 3. (Running virtualenv with interpreter \/usr\/bin\/python2)<\/p>\n which python3 will tell you where the python3 binary resides, adjust the path for virtualenv accordingly.<\/p>\n activate the environment:<\/p>\n source env\/bin\/activate<\/p>\n<\/blockquote>\n (This command path assumes that you stayed in the tutorial directory). Please also note, that this is not an executable script \u2013 you have to use source <\/strong>to use it with your bash terminal.<\/p>\n Notice, how (env) is prepended before your command prompt:<\/p>\n This means that the environment is active. Now you can run pip3 again, but this time pip3 will perform it\u2019s work on the virtual environment:<\/p>\n pip3 show randstr<\/p>\n pip3 show requests<\/p>\n<\/blockquote>\n should still yield nothing. The second line will also show nothing \u2013 showing that (if requests is installed system-wide) we are indeed in a virtual environment.<\/p>\n Now install randstr:<\/p>\n pip3 install randstr<\/p>\n<\/blockquote>\n and check again, if it is installed:<\/p>\n pip3 show randstr<\/p>\n<\/blockquote>\n This time it shows that randstr is installed. It has been installed into env\/lib\/python3.5\/site-packages:<\/p>\n While the environment ist still activated, let\u2019s write a small Python sample application:<\/p>\n nano sample.py<\/p>\n<\/blockquote>\n paste the following code, generating a random string using the new library we just installed:<\/p>\n from randstr import randstr <\/p>\n<\/blockquote>\n and save.<\/p>\n Run the code using python3:<\/p>\n python3 sample.py<\/p>\n<\/blockquote>\n while the environment is still active, this will work:<\/p>\n Now it\u2019s time to exit the environment, to see whether the code will still run:<\/p>\n deactivate<\/p>\n<\/blockquote>\n Your prompt will return back to normal. And<\/p>\n python3 sample.py<\/p>\n<\/blockquote>\n will throw an error message, about no module \u2018randstr\u2019 existing on your system. This is exactly the behaviour we want!<\/p>\n You can have a look at the env folder, seeing how it ships all the necessary things to run your Python code, including libraries, the python executable, pip, and more.<\/p>\n OK, now with the basics out of the way, what we want is to package a virtualenv alongside with our code, so that our application will run reliably and without disturbing other applications on our user\u2019s computers.<\/p>\n This is where dh-virtualenv <\/strong>enters the picture. dh-virtualenv is an addition to the Debian building scripts, which allows you to package virtual environments.<\/p>\n We need to create a basic package structure for our new package. This is where cookiecutter <\/strong>will help.<\/p>\n cookiecutter creates new projects for you from templates, thus reducing the overhead and time you spend on developing and getting your head around the many files which are required.<\/p>\n https:\/\/cookiecutter.readthedocs.io\/en\/latest\/<\/p>\n sudo apt install cookiecutter<\/p>\n<\/blockquote>\n Note: the package python3-cookiecutter will provide a Python module for Python 3. What we want is the application itself, which is installed with the cookiecutter package as seen above. This might pull in Python 2, but \u2013 oh well.<\/p>\n cookiecutter is not necessary for your end users, it is only used to create several files for your package.<\/p>\n create an example project directory, into which we will apply the template (I am still in the tutorial directory):<\/p>\n mkdir sampleproject<\/p>\n cd sampleproject<\/p>\n<\/blockquote>\n Using a special mold for dh-virtualenv we can set up many of the necessary files:<\/p>\n https:\/\/github.com\/Springerle\/dh-virtualenv-mold<\/a><\/p>\n cookiecutter https:\/\/github.com\/Springerle\/dh-virtualenv-mold.git<\/a><\/p>\n<\/blockquote>\n This will ask you several questions.<\/p>\n Note, that the folder should be named debian, even when packaging for Raspbian \u2013 therefore keep the name as debian. <\/p>\n This will install the following files:<\/p>\n Now you need to run the following commands, as per the instructions under the dh-virtualenv-mold:<\/p>\n This file will contain your release and version information for the package. You can update it using a special tool, dch<\/strong>.<\/p>\n This file is not a changelog for your application, but just a changelog for the packing of your application.<\/p>\n This file includes a special magic number \u201c9\u201d. (for compatibility issues, it\u2019s fine to leave it as it is)<\/p>\n This is the main file to set package settings, and dependencies on a Debian level. If your application depends, for example, on the omxplayer being installed, it will need to go in here as a dependency:<\/p>\n Source: sampleproject Package: sampleproject You will also want to edit the long Description.<\/p>\n Includes your initial settings. Not required for packaging.<\/p>\n Your copyright file, with your license (e.g. MIT). It\u2019s pre-filled with your name, year, e-Mail and \u201csome rights reserved\u201d.<\/p>\n This is a Makefile, to actually build your package. It is prefilled by the cookiecutter template.<\/p>\n This file allows you to create links during installation . The filename will include your project name instead of sampleproject<\/strong>.<\/p>\n Ref: https:\/\/stackoverflow.com\/questions\/9965717\/debian-rules-file-make-a-symlink<\/a><\/p>\n This file allows you to run additional setup steps after installation (e.g. activating your python script as a service). The filename will include your project name instead of sampleproject<\/strong>.<\/p>\n As far as I understand it this is for dh-virtualenv to install a newer python interpreter into the virtual environment to ship, if the system\u2019s (your development box) one is updated. The filename will include your project name instead of sampleproject<\/strong>.<\/p>\n This might or might not be the case, I have not tested it.<\/p>\n As mentioned above, we need a setup.py <\/strong>file. This is the standard way applications are packaged under Python (they ship with a setup.py, which is executed for various tasks related to packaging). <\/p>\n A simple setup.py can be seen on this page:<\/p>\n https:\/\/github.com\/benjaminirving\/python-debian-packaging-example\/blob\/master\/setup.py<\/a><\/p>\n Not all entries in this files are necessary. For instance, you can leave out the classifiers. I have the following setup.py:<\/p>\n Note: the version number and other information inside here are for your Python package (which will be created in the course of building a Debian package with your virtualenv).<\/p>\n Your code will now live in a subdirectory of the main sampleproject directory:<\/p>\n The subdirectory has the same name as the main directory in this case.<\/p>\n Note the __init__.py<\/p>\n The sample.py is the one we used above, but a bit reworked to look like this:<\/p>\n Additionally, I set up a virtual environment for testing while developing inside the main (top level) sampleproject directory:<\/p>\n virtualenv -p \/usr\/bin\/python3 sp_env<\/p>\n<\/blockquote>\n called sp_env for sample project environment<\/p>\n Entering the environment:<\/p>\n source sp_env\/bin\/activate<\/p>\n<\/blockquote>\n Install the randstr library into this environment:<\/p>\n pip3 install randstr<\/p>\n<\/blockquote>\n and now we can run the code:<\/p>\n python3 sampleproject\/sample.py<\/p>\n<\/blockquote>\n OK. Exit the environment (! important !)<\/strong>, and try to build the package again:<\/p>\n deactivate<\/p>\n dpkg-buildpackage -us \u2013uc<\/p>\n<\/blockquote>\n By default (because of the cookie cutter), your package will be created for installation in \/opt\/venvs\/:<\/p>\n New python executable in \/home\/pi\/tutorial\/sampleproject\/debian\/sampleproject\/opt\/venvs\/sampleproject\/bin\/python3<\/em><\/p>\n This can be changed in the debian\/rules <\/strong>file.<\/p>\n Now the package has been built, and deposited outside of the sampleproject top directory (inside the tutorial directory):<\/p>\n <\/p>\n You can install the .deb file using dpkg:<\/p>\n sudo dpkg -i sampleproject_0.2.1+nmu1_armhf.deb<\/p>\n<\/blockquote>\n See the installation results with <\/p>\n tree \/opt\/venvs<\/p>\n<\/blockquote>\n 127 directories and 945 files were installed.<\/p>\n Now you can try to execute the sampleproject using <\/p>\n \/opt\/venvs\/sampleproject\/bin\/sampleproject<\/p>\n<\/blockquote>\n The application will not run as (maybe) expected, but throw an error about randstr not being present. What gives?<\/p>\n The reason is that dh-virtualenv does not know about the requirement we have, to bundle the package randstr during the build process. This is the final piece of the puzzle. <\/p>\n The requirements need to be added to the setup.py<\/strong>, as a way to let pip know which additional packages need to be installed in the virtual environment which is being created.<\/p>\n add the following to setup.py:<\/p>\n install_requires=[<\/p>\n \u2018randstr\u2019<\/p>\n ]<\/p>\n<\/blockquote>\n The whole file then will look like this:<\/p>\n In my tests the requirements.txt placed at top-level did not <\/strong>influence the behaviour of dh-virtualenv and the Python packages actually included in the Debian package. If you still want it, here\u2019s how:<\/p>\n pip offers you a way to put out the exact dependencies you used for developing in the virtual environment. Enter the virtual environment:<\/p>\n source sp_env\/bin\/activate<\/p>\n<\/blockquote>\n And create the requirements.txt file:<\/p>\n pip3 freeze > requirements.txt<\/p>\n<\/blockquote>\n Now you can have a look at that file:<\/p>\n cat requirements.txt<\/p>\n<\/blockquote>\n Even though this file seems not to be used by dh-virtualenv (maybe it needs to go in a different subdirectory), it is a good reference for yourself, to see which packages you should put as dependencies into the install_requires part of setup.py.<\/p>\n Note that the file sampleproject.links offered us a convenient way to link this into the \/usr\/bin folder, I will therefore remove the comment sign for the next build:<\/p>\n With that out of the way, it\u2019s time to purge the sampleproject, and build it again, then install it. Don\u2019t forget to deactivate first!<\/p>\n deactivate<\/p>\n sudo apt purge sampleproject<\/p>\n dpkg-buildpackage \u2013us -uc<\/p>\n cd ..<\/p>\n sudo dpkg \u2013i sampleproject_0.2.1+nmu1_armhf.deb<\/p>\n<\/blockquote>\n This time, the package should be accessible using sampleproject:<\/p>\n which sampleproject<\/p>\n sampleproject<\/p>\n<\/blockquote>\n Ref: https:\/\/packaging.python.org\/discussions\/install-requires-vs-requirements\/<\/a><\/p>\n <\/p>\n \/opt\/venvs is not a very Debian \u201cplace\u201d to put a package.<\/p>\n The specifications are here:<\/p>\n http:\/\/refspecs.linuxfoundation.org\/FHS_3.0\/fhs\/index.html<\/a><\/p>\n https:\/\/unix.stackexchange.com\/questions\/10127\/why-did-my-package-get-installed-to-opt<\/a><\/p>\n http:\/\/refspecs.linuxfoundation.org\/FHS_3.0\/fhs\/ch04s06.html<\/a><\/p>\n Applications may use a single subdirectory under https:\/\/wiki.debian.org\/HowToPackageForDebian<\/a><\/p>\n https:\/\/www.debian.org\/doc\/debian-policy\/ch-opersys.html#file-system-hierarchy<\/a><\/p>\n \u201cThe FHS requirement that architecture-independent application-specific static files be located in The best location to me seems to be \/usr\/share<\/p>\n We need to edit two files:<\/p>\n in debian\/rules DH_VIRTUALENV_INSTALL_ROOT must be changed to \/usr\/share, like this:<\/p>\n and debian\/sampleproject.links must be changed:<\/p>\n Also, we will make a new entry into the changelog:<\/p>\n dch \u2013i<\/p>\n<\/blockquote>\nThe problem <\/h2>\n
pip<\/h2>\n
\n
virtualenv<\/h2>\n
\n
Practical part: Trying out virtualenv<\/h3>\n
\n
\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-17.png\" "\\"image\\"")
<\/a><\/p>\n\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-18.png\" "\\"image\\"")
<\/a><\/p>\n\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-19.png\" "\\"image\\"")
<\/a><\/p>\n\n
\n
\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-20.png\" "\\"image\\"")
<\/a><\/p>\n![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-21.png\" "\\"image\\"")
<\/a><\/p>\n\n
\n
\nprint(“hello world”)
\nprint(randstr())\n<\/p>\n\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-22.png\" "\\"image\\"")
<\/a><\/p>\n\n
\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-23.png\" "\\"image\\"")
<\/a><\/p>\nDebian virtualenv packaging with dh-virtualenv<\/h2>\n
cookiecutter<\/h2>\n
\n
\n
\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-24.png\" "\\"image\\"")
<\/a><\/p>\n![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-25.png\" "\\"image\\"")
<\/a><\/p>\n\n
sudo apt-get install build-essential debhelper devscripts equivs<\/pre>\n
sudo mk-build-deps --install debian\/control<\/pre>\n<\/blockquote>\n
To build the package later on, you will run the follwoing command from your project\u2019s top level directory:<\/font><\/pre>\n
\n
dpkg-buildpackage -uc -us \u2013b<\/pre>\n<\/blockquote>\n
Right now, though, the command will fail because setup.py is missing. We will get to setup.py and requirements.txt in a brief while:<\/font><\/pre>\n
\n
\/usr\/bin\/python3: can't open file 'setup.py': [Errno 2] No such file or directory<\/pre>\n<\/blockquote>\n
Information about the individual files<\/h2>\n
changelog<\/h3>\n
compat<\/h3>\n
control<\/h3>\n
\nSection: contrib\/python
\nPriority: extra
\nMaintainer: Maximilian Batz <???>
\nBuild-Depends: debhelper (>= 9), python, python-dev, dh-virtualenv (>= 0.10), tar
\nStandards-Version: 3.9.5
\nHomepage: <\/em>https:\/\/picockpit.com<\/em><\/a><\/p>\n
\n<\/em><\/p>\n
\nArchitecture: any
\nPre-Depends: dpkg (>= 1.16.1), python2.7 | python3, ${misc:Pre-Depends}
\nDepends: ${python:Depends}, ${misc:Depends}
\nDescription: An example package to demonstrate virtualenv Debian packaging with dh-virtualenv
.
This is a distribution of “sampleproject” as a self-contained
Python virtualenv wrapped into a Debian package (“omnibus” package,
all passengers on board). The packaged virtualenv is kept in sync with
the host’s interpreter automatically.
.
See <\/em>https:\/\/github.com\/spotify\/dh-virtualenv<\/em><\/a> for more details.<\/em><\/p>\ncookiecutter.json<\/h3>\n
copyright<\/h3>\n
rules<\/h3>\n
sampleproject.links<\/h3>\n
sampleproject.postinst<\/h3>\n
sampleproject.triggers<\/h3>\n
setup.py<\/h2>\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-26.png\" "\\"image\\"")
<\/a><\/p>\nStructure for your code<\/h2>\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-27.png\" "\\"image\\"")
<\/a><\/p>\n![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-28.png\" "\\"image\\"")
<\/a><\/p>\n\n
\n
\n
\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-29.png\" "\\"image\\"")
<\/a><\/p>\n\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-30.png\" "\\"image\\"")
<\/a><\/p>\n\n
\n
\n
requirements \/ dependencies<\/h2>\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-31.png\" "\\"image\\"")
<\/a><\/p>\n\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-32.png\" "\\"image\\"")
<\/a><\/p>\n\n
\n
\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-33.png\" "\\"image\\"")
<\/a><\/p>\n![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-34.png\" "\\"image\\"")
<\/a><\/p>\n\n
\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-35.png\" "\\"image\\"")
<\/a><\/p>\nBonus tip: changing the installation location<\/h2>\n
\n
\/usr\/lib<\/code>. If an application uses a subdirectory, all architecture-dependent data exclusively used by the application must be placed within that subdirectory.<\/p>\n\/usr\/share<\/code> is relaxed to a suggestion. In particular, a subdirectory of \/usr\/lib<\/code> may be used by a package<\/strong> (or a collection of packages) to hold a mixture of architecture-independent and architecture-dependent files. However, when a directory is entirely composed of architecture-independent files, it should be located in \/usr\/share<\/code><\/strong>.\u201d<\/p>\n![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-36.png\" "\\"image\\"")
<\/a><\/p>\n![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-37.png\" "\\"image\\"")
<\/a><\/p>\n\n
![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-38.png\" "\\"image\\"")
<\/a><\/p>\n![\"image\"](\"https:\/\/pi3g.com\/wp-content\/uploads\/2019\/04\/image_thumb-39.png\" "\\"image\\"")
<\/a><\/p>\n