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.

Travailler avec les sources

/!\ Attention ! Ces instructions ne valent que pour les branches 1.6.x et antérieures ''' Pour les branches 1.7+ et master, il n'y a plus besoin de build. Jelix s'installer avec Composer.

Cette page contient des informations nécessaires à toutes personnes voulant, soit créer une version personnalisée de Jelix 1.6 et inférieur, soit proposer des patchs corrigeant des bugs ou apportant des améliorations sur jelix 1.6 et inférieur.

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 appellera 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 contexte : 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 Git (git 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 git
  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

Nous utilisons Git pour gérer les sources de Jelix. Vous devez donc installer git sur votre machine et ensuite cloner le dépôt git de jelix. le dépôt est stocker sur le site github.com. Voir les instructions sur https://github.com/jelix/jelix pour récupérer les sources.

Par le passé, nous avons d'abord utilisé Subversion (janvier 2006 - juin 2009), puis Mercurial hébergé sur notre propre serveur (juin 2009 - mars 2010) puis sur on Bitbucket (Mars 2010 - aout 2011).

Le dépôt git sur github contient les branches des version 1.2.x et supérieurs. Pour les branches plus anciennes, les dépôts sont restés sur https://bitbucket.org/jelix/

Récupération des sources sous Windows

La première installation de git

Sous windows, vous avez suivi ceci http://help.github.com/win-set-up-git/

Vous obtenez vos fichiers id_rsa* dans c:\users\name\.ssh donc pour pouvoir faire un "git clone" il faudra la première fois uniquement, importer la clé rsa privé avec puttygen. Une fois importée vous pourrez l'enregistrer au "format" putty.

Cloner

Lancer "pageant.exe", sélectionnez votre clé publique, entrez la passphrase, et vous pourrez enfin taper "git clone" dans "Git Bash"

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 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épôt, et contenant donc lib/ etc. :

   /home/laurent/projets/jelix/src/

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_JELIX =
WITH_BYTECODE_CACHE = auto

ENABLE_DEVELOPER = 1

STRIP_COMMENT = 
ENABLE_OPTIMIZED_SOURCE = 

PACKAGE_TAR_GZ = 
PACKAGE_ZIP = 

Générer une version de travail sous windows, le path sera par exemple de la forme :

MAIN_TARGET_PATH = C:/WEB/DOCUMENT_ROOT/www_jelix

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_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épôt. Le Makefile accepte différentes cibles, qui permettent de générer des répertoires 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éférence.


Retour au sommaire

Last modified 3 years ago Last modified on Nov 24, 2015, 9:20:11 PM