From 685606fdb60622d2533dc8aab790d705dfb1712b Mon Sep 17 00:00:00 2001 From: Yohann D'ANELLO Date: Fri, 20 Nov 2020 17:32:26 +0100 Subject: [PATCH] Documentation on packaging --- docs/deployment.rst | 311 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 312 insertions(+) create mode 100644 docs/deployment.rst diff --git a/docs/deployment.rst b/docs/deployment.rst new file mode 100644 index 0000000..1a4860d --- /dev/null +++ b/docs/deployment.rst @@ -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 +`_. + +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 +`_, 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 ``_. + 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 + + 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 + + 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. diff --git a/docs/index.rst b/docs/index.rst index e7e3569..5a3af7b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,7 @@ Bienvenue dans la documentation de Squirrel Battle ! install-dev tests display/index + deployment .. toctree:: :maxdepth: 3