Documentation on packaging

This commit is contained in:
Yohann D'ANELLO 2020-11-20 17:32:26 +01:00
parent d697c50268
commit 685606fdb6
2 changed files with 312 additions and 0 deletions

311
docs/deployment.rst Normal file
View File

@ -0,0 +1,311 @@
Déploiement du projet
=====================
.. _PyPI: https://pypi.org/project/squirrel-battle/
.. _AUR: https://aur.archlinux.org/packages/python-squirrel-battle/
.. _Debian: https://gitlab.crans.org/ynerant/squirrel-battle/-/jobs/artifacts/master/raw/build/python3-squirrelbattle_3.14_all.deb?job=build-deb
.. _installation: install.html
À chaque nouvelle version du projet, il est compilé et déployé dans PyPI_, dans
l'AUR_ et un paquet Debian_ est créé, voir la page d'installation_.
PyPI
----
Définition du paquet
~~~~~~~~~~~~~~~~~~~~
.. _setup.py: https://gitlab.crans.org/ynerant/squirrel-battle/-/blob/master/setup.py
La documentation sur le packaging dans PyPI_ est disponible `ici
<https://packaging.python.org/tutorials/packaging-projects/>`_.
Le fichier `setup.py`_ contient l'ensemble des instructions d'installation du
paquet ainsi que des détails à fournir à PyPI :
.. code:: python
#!/usr/bin/env python3
import os
from setuptools import find_packages, setup
with open("README.md", "r") as f:
long_description = f.read()
setup(
name="squirrel-battle",
version="3.14",
author="ynerant",
author_email="ynerant@crans.org",
description="Watch out for squirrel's knifes!",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://gitlab.crans.org/ynerant/squirrel-battle",
packages=find_packages(),
license='GPLv3',
classifiers=[
"Development Status :: 4 - Beta",
"Environment :: Console :: Curses",
"License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
"Natural Language :: French",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.6",
"Programming Language :: Python :: 3.7",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"Topic :: Games/Entertainment",
],
python_requires='>=3.6',
include_package_data=True,
package_data={"squirrelbattle": ["assets/*"]},
entry_points={
"console_scripts": [
"squirrel-battle = squirrelbattle.bootstrap:Bootstrap.run_game",
]
}
)
Ce fichier contient le nom du paquet, sa version, l'auteur et son contact,
sa description en une ligne et sa description longue, le lien d'accueil du projet,
sa licence, ses classificateurs et son exécutable.
Le paramètre ``entry_points`` définit un exécutable nommé ``squirrel-battle``,
qui permet de lancer le jeu.
Installation locale du paquet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
L'installation du paquet localement dans son environnement Python (virtuel ou non)
peut se faire en exécutant ``pip install -e .``.
Génération des binaires
~~~~~~~~~~~~~~~~~~~~~~~
Les paquets ``setuptools`` (``python3-setuptools`` pour APT, ``python-setuptools``
pour pacman) et ``wheel`` (``python3-wheel`` pour APT, ``python-wheel`` pour pacman)
sont nécessaires. Une fois installés, il faut appeler la commande :
.. code:: bash
python3 setup.py sdist bdist_wheel
Une fois cela fait, le dossier ``dist/`` contiendra les archives à transmettre à PyPI.
Publier sur PyPI
~~~~~~~~~~~~~~~~
Il faut avant tout avoir un compte sur PyPI. Dans `votre compte PyPI
<https://pypi.org/manage/account/>`_, il faut générer un jeton d'accès API.
Dans le fichier ``.pypirc`` dans le répertoire principal de l'utilisateur,
il faut ajouter le jeton d'accès :
.. code::
[pypi]
username = __token__
password = pypi-my-pypi-api-access-token
Cela permet de s'authentifier directement par ce jeton.
Ensuite, il faut installer ``twine``, qui permet de publier sur PyPI.
Il suffit ensuite d'appeler :
.. code:: bash
twine upload dist/*
pour envoyer le paquet sur PyPI.
.. note::
À des fins de tests, il est possible d'utiliser le dépôt `<https://test.pypi.org>`_.
Les différences sont au niveau de l'authentification, où il faut l'en-tête
``[testpypi]`` dans le ``.pypirc``, et il faut envoyer le paquet avec
``twine upload --repository testpypi dist/``.
Publier dans l'AUR
------------------
Fonctionnement du packaging
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _python-squirrel-battle: https://aur.archlinux.org/packages/python-squirrel-battle/
.. _python-squirrel-battle-git: https://aur.archlinux.org/packages/python-squirrel-battle-git/
Deux paquets sont publiés dans l'AUR (Arch User Repository) :
- python-squirrel-battle_
- python-squirrel-battle-git_
Le packaging dans Arch Linux se fait en commitant un fichier ``PKGBUILD`` dans
le dépôt à l'adresse ``ssh://aur@aur.archlinux.org/packagename.git``,
en remplaçant ``packagename`` par le nom du paquet.
Le second paquet compile directement le jeu à partir de la branche ``master``
du dépôt Git. Le fichier ``PKGBUILD`` dispose de cette structure :
.. code::
# Maintainer: Yohann D'ANELLO <ynerant@crans.org>
pkgbase=squirrel-battle
pkgname=python-squirrel-battle-git
pkgver=3.14
pkgrel=2
pkgdesc="Watch out for squirrel's knives!"
arch=('any')
url="https://gitlab.crans.org/ynerant/squirrel-battle"
license=('GPLv3')
depends=('python')
makedepends=('python-setuptools')
depends=('noto-fonts-emoji')
checkdepends=('python-tox')
ssource=("git+https://gitlab.crans.org/ynerant/squirrel-battle.git")
sha256sums=("SKIP")
pkgver() {
cd pkgbase
git describe --long --tags | sed -r 's/^v//;s/([^-]*-g)/r\1/;s/-/./g'
}
build() {
cd $pkgbase
python setup.py build
}
check() {
cd $pkgbase
tox -e py3
tox -e linters
}
package() {
cd $pkgbase
python setup.py install --skip-build \
--optimize=1 \
--root="${pkgdir}"
install -vDm 644 README.md \
-t "${pkgdir}/usr/share/doc/${pkgname}"
install -vDm 644 LICENSE -t "${pkgdir}/usr/share/licenses/${pkgname}"
}
Ces instructions permettent de cloner le dépôt, l'installer et exécuter des tests,
en plus de définir les attributs du paquet.
Le fichier ``PKGBUILD`` du paquet ``python-squirrel-battle``, synchronisé avec
les releases, est plus ou moins similaire :
.. code::
# Maintainer: Yohann D'ANELLO <ynerant@crans.org>
pkgbase=squirrel-battle
pkgname=python-squirrel-battle
pkgver=3.14
pkgrel=2
pkgdesc="Watch out for squirrel's knives!"
arch=('any')
url="https://gitlab.crans.org/ynerant/squirrel-battle"
license=('GPLv3')
depends=('python')
makedepends=('python-setuptools')
depends=('noto-fonts-emoji')
checkdepends=('python-tox')
source=("https://gitlab.crans.org/ynerant/squirrel-battle/-/archive/v3.14/$pkgbase-v$pkgver.tar.gz")
sha256sums=("6090534d598c0b3a8f5acdb553c12908ba8107d62d08e17747d1dbb397bddef0")
build() {
cd $pkgbase-v$pkgver
python setup.py build
}
check() {
cd $pkgbase-v$pkgver
tox -e py3
tox -e linters
}
package() {
cd $pkgbase-v$pkgver
python setup.py install --skip-build \
--optimize=1 \
--root="${pkgdir}"
install -vDm 644 README.md \
-t "${pkgdir}/usr/share/doc/${pkgname}"
install -vDm 644 LICENSE -t "${pkgdir}/usr/share/licenses/${pkgname}"
}
Il se contente ici de télécharger l'archive de la dernière release, et de travailler
dessus.
Mettre à jour
~~~~~~~~~~~~~
Pour mettre à jour le dépôt, une fois les dépôts
``ssh://aur@aur.archlinux.org/python-squirrel-battle.git`` et
``ssh://aur@aur.archlinux.org/python-squirrel-battle-git.git`` clonés,
il suffit de mettre à jour le paramètre ``pkgver`` pour la bonne version,
de régénérer le fichier ``.SRCINFO`` en faisant
``makepkg --printsrcinfo > .SRCINFO``, puis de committer/pousser.
Construction du paquet Debian
-----------------------------
Structure du paquet
-------------------
L'ensemble des instructions pour construire le paquet Debian est situé dans le
dossier ``debian/``.
Le fichier ``changelog`` est à modifier à chaque nouvelle version, le fichier
``compat`` contient la version minimale de Debian requise (``10`` pour Debian
Buster), le fichier ``copyright`` contient la liste des fichiers distribués sous
quelle licence (ici GPLv3), le fichier ``control`` contient les informations du
paquet, le fichier ``install`` les fichiers de configuration à installer
(ici le fix de l'affichage de l'écurueil), et enfin le fichier ``rules`` l'ensemble
des instructions à exécuter pour installer.
Le paquet ``fonts-noto-color-emoji`` est en dépendance pour le bon affichage
des émojis.
Mettre à jour le paquet
-----------------------
Pour changer la version du paquet, il faut ajouter des lignes dans le fichier
``changelog``.
Construire le paquet
--------------------
Il faut partir d'une installation de Debian.
D'abord on installe les paquets nécessaires :
.. code::
apt update
apt --no-install-recommends install build-essential debmake dh-python debhelper python3-all python3-setuptools
On peut ensuite construire le paquet :
.. code:: bash
dpkg-buildpackage
mkdir build && cp ../*.deb build/
Le paquet sera installé dans ``build/python3-squirrel-battle_3.14_all.deb``.
Le paquet Debian_ est construit par l'intégration continue Gitlab et ajouté
à chaque release.

View File

@ -37,6 +37,7 @@ Bienvenue dans la documentation de Squirrel Battle !
install-dev install-dev
tests tests
display/index display/index
deployment
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 3