wiki:fr/sources
developer.jelix.org is not used any more and exists only for history. Post new tickets on the Github account.
developer.jelix.org n'est plus utilisée, et existe uniquement pour son historique. Postez les nouveaux tickets sur le compte github.

Version 20 (modified by laurentj, 10 years ago) (diff)

--

Travailler avec les sources

Cette page contient des informations nécessaires à toutes personnes voulant, soit créer une version personnalisée de Jelix, soit proposer des patchs corrigeant des bugs ou apportant des amélioration.

Principes

Travailler avec les sources de Jelix est assez différent des projets PHP traditionnels, en ce sens que les sources que l'on trouve dans le dépôt des sources, n'est pas directement utilisable par PHP. En clair, le contenu qui est proposé dans les archives en téléchargement, est légèrement différent de ce qui est dans le dépôt.

En effet, certains fichiers sources de Jelix contiennent des directives spéciales permettant à un pré-processeur, de générer un fichier source final qui sera différent selon des paramètres qu'on lui fournit. Ce pré-processeur est piloté par un script, que l'on appelera un "générateur" de sources finales (le résultat, les sources finales, sont appelées aussi un "build"). Cela permet de fournir des versions différentes de Jelix

  • en fonction d'une version de PHP
  • optimisée selon le context : optimisée pour un environnement en production, ou contenant des outils et fonctions supplémentaires pour aider au développement.
  • etc..

Et plus tard, on pourra aussi en générer en fonction de l'arborescence finale souhaitée : configuré pour fonctionner sans documentRoot, ou avec documentRoot.

Ainsi, quand on travail sur jelix, on suit ces étapes :

  1. récupération de la dernière version de jelix à partir du dépôt principal des sources Mercurial (hg clone etc)
  2. création d'un fichier de paramètres pour le générateur (un fichier ini)
  3. modification des fichiers sources de jelix (correction de bug, amélioration, nouvelle fonctionnalité etc..)
  4. lancement du générateur de sources finales. On obtient un "build"
  5. test du build avec une application, et en particulier testapp (qui est fournie dans le dépôt) qui contient tout les tests unitaires
  6. si les tests sont concluants, le développeur propose son patch et débute alors le processus de review.

Pour ceux qui veulent juste avoir une version optimisée/personnalisée, seules ces étapes sont nécessaires :

  1. récupération de la dernière version de jelix dans le dépôt mercurial
  2. création d'un fichier de paramètres pour le générateur afin d'obtenir la version souhaitée
  3. lancement du générateur de sources finales.
  4. On obtient un "build" que l'on peut utiliser sur son serveur.

Récupérer les sources

Jusqu'en juillet 2009, les sources étaient gérés par l'outil Subversion. Depuis, nous utilisons Mercurial.

Pour récupérer les sources, il vous faut donc installer Mercurial sur votre machine, et ensuite cloner l'un des dépôts disponibles. Il y en a plusieurs, suivant les branches. Le dépôt principal étant jelix-trunk.

Pour rappel, Mercurial est outil de contrôle de version : il permet d'enregistrer et d'historier toutes les modifications faites sur les fichiers sources d'un projet.

Voici l'adresse du dépôt principal de Jelix, pour les contributeurs "anonymes" :

   http://bitbucket.org/jelix/jelix-trunk/

Adresse du dépôt, pour les contributeurs qui ont un accès en écriture sur le dépôt :

   ssh://hg@bitbucket.org/jelix/jelix-trunk

Cela donne donc en ligne de commande :

hg clone http://bitbucket.org/jelix/jelix-trunk/

ou

hg clone ssh://hg@bitbucket.org/jelix/jelix-trunk

jelix-trunk constitue la branche principale du framework : il contient la prochaine version majeure en cours de développement (1.2, 1.3 etc.). Si vous voulez récupérer d'autres branches ou versions officielles, en particulier les branches de maintenances des versions sorties comme la branche 1.0.x (1.0, 1.0.1, 1.0.2...), leurs noms sont jelix-1.0.x, jelix-1.1.x etc. Voir la liste sur la page du projet sur bitbucket.

Récupération des sources sous Windows pour les contributeurs "officiels"

Sous windows, TortoiseHg risque fort de ne pas trouver votre clé SSH, donc pour l'y aider on exécute le programme suivant C:\Program Files\TortoiseHg\Pageant.exe. Ensuite fournissez votre clé privée (et éventuellement votre passphrase) puis procédez comme ci dessus pour cloner

Arborescence

Voici les différents répertoires que vous récupérez :

  build/     les outils de génération de sources
  lib/       les bibliothèques de jelix
  temp/      repertoire temporaire pour les applications jelix
  testapp/   application qui permet de tester le framework

Les outils de constructions

Les sources obtenues via le dépôt mercurial ne peuvent pas être utilisable directement par PHP. Pour pouvoir utiliser Jelix, il faut générer les sources finales interprétables par PHP. Pour ce faire il y a un script build/buildjelix.php. C'est le fameux "générateur". C'est une sorte de makefile. Il prend en argument un nom de fichier ini qui déclare des paramètres de génération. Vous en avez quelques exemples dans le repertoire build/config/.

Générer une version de travail

Avant de faire des modifications, il faut préparer votre environnement. Vous devez avoir le répertoire contenant les sources du dépôt, et le répertoire qui contiendra une version utilisable du framework. Par exemple :

Pour le répertoire du dépot, et contenant donc lib/ etc. :

   /home/laurent/projets/jelix/hg/jelix-trunk

Pour le répertoire cible, contenant la version interprétable/utilisable par php

   /home/laurent/projets/jelix/tests/ 

Créez un fichier monbuild.ini, sur le modèle de ceux que vous trouvez dans build/config (jelix-test.ini par ex). Il contiendra alors ce genre de paramètres :

MAIN_TARGET_PATH = /home/laurent/projets/jelix/tests/
EDITION_NAME = 
PHP_VERSION_TARGET =

ENABLE_PHP_FILTER =
ENABLE_PHP_JSON =
ENABLE_PHP_XMLRPC =
ENABLE_PHP_JELIX =
WITH_BYTECODE_CACHE = auto

ENABLE_DEVELOPER = 1

STRIP_COMMENT = 
ENABLE_OPTIMIZED_SOURCE = 

PACKAGE_TAR_GZ = 
PACKAGE_ZIP = 

Vous pouvez avoir une liste complète des paramètres et leur signification en tapant dans une console :

  php build/buildjelix.php -h

Pour générer les sources, vous lancez la commande :

  php build/buildjelix.php monbuild.ini

Même principe pour l'application de test testapp. Mais il faut utiliser un autre script build/buildapp.php avec le fichier de config adéquate, dont un modèle, testapp-test.ini, se trouve dans build/config/.

  php build/buildapp.php montestapp.ini

Note: il faut lancer le build à chaque modification dans les sources de jelix, avant de le tester.

Générer un package

Le principe est exactement le même que pour générer une version de travail. Vous avez par exemple : /home/laurent/projets/jelix/dist/ pour le répertoire qui contiendra les futurs zip/tar.gz

Créez un nouveau fichier ini mondist.ini sur le modèle de monbuild.ini, en indiquant ce répertoire et en activant les options PACKAGE_TAR_GZ et/ou PACKAGE_ZIP

MAIN_TARGET_PATH = /home/laurent/projets/jelix/dist/
EDITION_NAME = 
PHP_VERSION_TARGET =

ENABLE_PHP_FILTER =
ENABLE_PHP_JSON =
ENABLE_PHP_XMLRPC =
ENABLE_PHP_JELIX =
WITH_BYTECODE_CACHE = auto

ENABLE_DEVELOPER = 1
STRIP_COMMENT = 
ENABLE_OPTIMIZED_SOURCE = 

PACKAGE_TAR_GZ = 1
PACKAGE_ZIP = 1

et ensuite :

  php build/buildjelix.php mondist.ini

Vous aurez alors dans /home/laurent/projets/jelix/dist/ des archives prêtes à être distribuées.

Utilisation du Makefile

Il existe un fichier makefile, utilisable par la commande Make, qui appel les scripts de build pour jelix et autres applications stockées dans le dépot. Le Makefile accepte différentes cibles, qui permettent de générer des repertoires de travail ou des paquets à distribuer avec les paramètres standards. Tapez simplement make pour en avoir la liste.

Toutefois, il n'est en principe pas à utiliser et est en fait surtout utilisé sur le serveur de jelix.org, pour générer chaque jour des paquets téléchargeables de la toute dernière version de Jelix, et générer la documentation de réference.


Retour au sommaire