KBibTeX/Développement
Ressources diverses utiles
Les liens suivants se rapportent à d'autres pages web pages ou ressources en rapport avec le développement de KBibTeX.
Démarrage rapide pour exécuter KBibTeX à partir de Git
Une méthode rapide et facile pour récupérer, compiler, et exécuter KBibTeX à partir de Git, par exemple pour le dernier code de la branche master , est de récupérer le script Bash run-kbibtex.sh du dépôt Git relatif à 'KBibTeX' de Thomas Fischer.
Pour lancer le script, soit vous le rendez exécutable et vous le lancez par
./run-kbibtex.sh
soit vous l'invoquez par
bash run-kbibtex.sh
Par défaut le script va cloner le dépôt Git de KBibTeX vers un répertoire temporaire, le compiler, l'installer dans un dossier temporaire, et exécuter cette installation temporaire de KBibTeX.
Il n'est pas utile d'exécuter ce script en tant que root ni avec sudo. Il ne va faire aucune modification permanente sur votre système. Pour compiler KBibTeX, des outils variés et des bibliothèques de développement doivent d'abord être disponibles, c'est à dire installés via le système de gestion de paquets de la distribution.
Il existe un fichier README.txt qui explique le script de manière plus approfondie.
Récupérer le code source
Les sources de KBibTeX sont disponibles dans Git KDE, le nom du dépôt est kbibtex. La manière de cloner un dépôt Git est expliquée dans les Recettes Git de TechBase. En résumé, exécutez la commande suivante dans votre terminal:
git clone git://anongit.kde.org/kbibtex
Vous pouvez voir le code source de KBibTeX sur le serveur Git de KDE.
Branches
Le développement principal (Main) se fait dans la branche maître (appelée master). L'objectif est que cette branche soit fonctionnelle et stable la lplupart du temps, mais cela n'est pas garanti. Utilisez cette branche pour essayer les nouvelles fonctions.
Pour les versions, des branches de version sont créées. La règle de nommage est kbibtex/numéroDeVersion, où le numéro de version est quelque chose comme 0.6. Les versions actuelles sont des labels ('tags') de validation (commit) à l'intérieur de cette branche, par exemple v0.5.1. Il n'y aura pas de branches pour les versions concernant la correction de bogues, par exemple pas de kbibtex/0.6.1.
Pour les bogues ou les fonctionnalités qui nécessitent plusieurs validations (commit) et où des validations individuelles peuvent casser master ou une branche de version, les "branches de fonctionnalités" sont utilisées. Ces branches sont supposées suivre master (typique pour les fonctionnalités) ou une branche de version (typique pour les bogues). Les branches pour les bogues doivent être fusionnées dans la branche de version où le bogue a été signalé ainsi que dans la branche master ( principale - pour les versions futures). Les branches de fonctions sont fusionnées dans la branche principale (master), dans certains cas, en branches de versions, où aucune version n'a encore été étiquetée, et seulement dans de rares cas, reportées à postériori pour les branches de version avec des versions publiées. Un exemple de branche de fonctionnalité serait feature/zotero, qui peut contenir le code d'une prise en charge améliorée de Zotero. Les noms des branches associées aux rapports de bogues sont bugs/bugsystemnumber (par exemple bugs/kde338375), où bugsystem serait kde ou le nom d'une distribution Linux et numéro, le numéro du bogue actuel. Les branches de fonctionnalités commencent par feature/ suivi d'un nom descriptif court pour cette fonctionnalité (toutes en minuscules, sans espaces). Les branches fusionnées seront supprimées après un certain temps.
Compiler le code
Les instructions suivantes donnent des informations sur la manière de de compiler KBibTeX à partir de la ligne de commande. Les instructions sont similaires mais diffèrent légèrement entre les compilations basées sur KDE4 (par exemple la branche kbibtex/0.5) et celles basées sur KDE Frameworks 5 (par exemple la branche master). En compilant KBibTeX à partir d'un IDE comme KDevelop ou Qt Creator, ces initialisations doivent également être réalisées.
Exécuter CMake
KBibTeX est configuré en utilisant CMake. Il existe quelques options particulières pour la configuration de ce projet:
CMAKE_INSTALL_PREFIX:PATHdonne l'emplacement de l'installation. Il existe un nombre de choix disponibles pour cette option :- L'emplacement de votre installation KDE, par exemple /usr. Les commandes
kde4-config --prefix(compilations KDE4) oukf5-config --prefix(compilations KDE Frameworks 5) affichent cet emplacement. En choisissant cette option vous devrez probablement avoir les droits root (par exemple via sudo) pour la présente installation. Attention: ce choix interfère avec la gestion des archives. - Un répertoire en dehors du controle de la gestion de l'archive, par exemple /usr/local. Nécessite d'initialiser les quelques variables d'environnement décrites ci-dessous. Cette installation reste disponible au-delà des redémarrages et pour tous les utilisateurs. En choisissant cette option, il est probable que vous devrez avoir les droits root (par exemple via sudo) pour la présente installation.
- Un répertoire accessible en écriture par l'utilisateur comme /tmp/usr ou ~/usr. Similaire au choix ci-dessus, il nécessite d'initialiser certaines variables d'environnement, mais pas les droits « root ». Plusieurs distributions sont configurées pour vider /tmp au redémarrage.
- L'emplacement de votre installation KDE, par exemple /usr. Les commandes
CMAKE_BUILD_TYPEdetermine la quantité d'informations de deboggage incluse dans le code final. Les utilisateurs réguliers peuvent la positionner àrelease, les développeurs àdebug, et pour la mise au point pas-à-pas, àdebugfullc'est ce qui fonctionne le mieux. Toutes les options sont discutées dans la documentation CMake dans TechBase.
Un exemple complet ressemble à ceci:
cmake -DCMAKE_INSTALL_PREFIX:PATH=/tmp/usr -DCMAKE_BUILD_TYPE=debug ../kbibtex
Compilation
Le Make de GNU est le choix par défaut pour la compilation du code source. Le nombre de processus parallèles doit être précisé pour raccourcir le temps restant sur les systèmes multi-coeurs. La priorité des tâches de compilation peut être abaissée.
nice -n 16 make -j$(nproc)
Pour que make utilise ninja, l'instruction cmake ci-dessus doit inclure l'argument -GNinja. La combinaison à la fois de cmake et de ninja pourrait ressembler à ceci:
cmake -GNinja -DCMAKE_INSTALL_PREFIX:PATH=/tmp/usr -DCMAKE_BUILD_TYPE=debug ../kbibtex && ninja
Installation
KBibTeX utilise la technologie KParts de KDE, qui nécessite que vous aayez installé quelques bibliothèques. KBibTeX peut ne pas fonctionner correctement si les étapes suivantes sont omises.
En exécutant
make install
vous installerez KBibTeX dans le répertoire comme spécifié plus tôt en tant que préfixe d'installation. En fonction de votre choix pour le préfixe d'installation, cette commande doit être exécutée avec sudo ou alike.
A moins que le préfixe d'installation ne soit le répertoire d'installation de KDE, les variables d'environnement suivantes doivent être initialisées. Vous pouvez les initialiser temporairement dans une session shell active, ou d'une manière permanente dans la configuration de votres shell, ou encore créer un petit script de shell qui à la fois initialise ces variables et exécute votre installation de KBibTeX personnalisée.
- Seulement pour KDE4: initialiser la variable
KDEDIRSpour inclure le répertoire d'installation de KDE et celui de KBibTeX, par exemple /usr:/tmp/usr - Seulement pour KF5: initialisez la variable
QT_PLUGIN_PATHpour inclure le répertoire des greffons (plugin) dans le répertoire des bibliothèques du répertoire d'installation de KBibTeX, par exemple /usr/lib/plugins:/usr/lib/qt5/plugins:/tmp/usr/lib64/plugins/ - Initialiser la variable
LD_LIBRARY_PATHvers le répertoire des bibliothèques à dans le répertoire d'installation de KBibTeX, par exemple /tmp/usr/lib64 - Initialisez la variable
XDG_DATA_DIRSpour inclure les répertoires de données partagées du repertoire d'installation de KDE, celui de KBibTeX, ainsi que les autres préfixes associés, par exemple /usr/share:/usr/local/share:/tmp/usr/share
Exécuter kbuildsycoca4 (KDE4) ou kbuildsycoca5 (KDE Frameworks 5) pour que le sous-système KDE connaisse les nouvelles bibliothèques.
Attention
Maintenant KBibTeX peut être exécuté, comme indiqué dans cet exemple :
/tmp/usr/bin/kbibtex
Cookbook de Git
Un certain nombre de pages dans TechBase, UserBase, et Community présentent l'utilisation de Git pour la gestion du code source. Cette section ne montre que quelques exemples sur la façon dont Git est utilisé pour KBibTeX.
Créer une branche de développement de fonction ou de correction de bogue
Dans l'exemple ci-dessous, replacez xxxx par un nom court et concis représentant une fonctionalité à développer (comme expliqué ci-dessus). Les branches relatives aux corrections de bogues sont créées de manière similaire, mais suivent la structure bugs/kdeNNNN, où NNNN est le numéro de bogue dans le suivi des bogues de KDE. Les bogues dans les autres gestionnaires de bogues tel que Gna! ou votre distribution, peuvent être numérotés avec un préfixe différent tel que bugs/gnaNNNN ou bien bugs/gentooNNNN.
git branch --track feature/xxxx origin/master && git checkout feature/xxxx
Pousser une branche de fonctionalité locale ou de correction de bogue
Pour minimiser le risque de perturber le répertoire officiel de KBibTeX ou lorsque vous n'avez pas d'accès en écriture, vous pouvez pousser (push) vos branches locales dans un autre dépôt Git pour permettre aux autres personnes de voir vos modifications. Dans l'exemple ci-dessous, personalpublicclone est votre propre dépôt Git publique dans lequel vous voulez faire le push.
Pour publier vos modifications, utilisez une commande comme :
git push personalpublicclone feature/xxxx:feature/xxxx
Les autres utilisateurs peuvent ajouter votre dépôt à leur clône local du KBibTeX de Git et ainsi clôner votre branche (en supposant dans cet exemple qu'elle soit déja sur le serveur Git de KDE) :
git remote add someonespublicclone [email protected]:clones/kbibtex/NAME/kbibtex # run once git fetch someonespublicclone feature/xxxx && git checkout feature/xxxx # every time to get updates git remote rm someonespublicclone && git checkout master && git branch -D feature/xxxx # to erase branch
Créer des branches de livraison et des labels
Pour créer une branche de version à partir du master et le pousser (push) dans origin, exécutez :
git checkout -b kbibtex/0.6 master && git push origin kbibtex/0.6
Pour poser un label de version dans une branche de version, exécutez les commandes suivantes :
git checkout kbibtex/0.6 # be in right branch git pull --ff-only # get latest changes from origin git status # just check that everything is ok git tag -s -u GPGKEY -m "Tagging 0.6" v0.6 # actual tagging, GnuPG signed git push --tags # explicitly push tag to origin
Créer une version
Information
Pour créer une version, utilisez les scripts Ruby du répertoire git.kde.org:releaseme.git . La génération de l'archive KBibTeX est configurée par les fichiers kbibtex.rb et kbibtexrc. Configurez ces fichiers ou appelez kbibtex.rb avec les arguments corrects, tels que :
./kbibtex.rb --src=file:///${HOME}/git/kbibtex --version=0.6.0 --no-doc --no-l10n
Atteindre la documentation et les fichiers de traduction est la partie qui prend le plus de temps dans ce processus.
Les hachages cryptographiques détachés peuvent être créés et signés comme suit:
sha512sum kbibtex-0.6.0.tar.xz >kbibtex-0.6.0.tar.xz.sha512 gpg --default-key GPGKEY --output kbibtex-0.6.0.tar.xz.sha512.asc --detach-sign --armor kbibtex-0.6.0.tar.xz.sha512 gpg --default-key GPGKEY --output kbibtex-0.6.0.tar.xz.asc --detach-sign --armor kbibtex-0.6.0.tar.xz