# ilib_build_jar

Construit une archive JAR de packages Java

## Séquence d'appel

                ilib_build_jar(jarFilePath, packageNames[, sourcePath[, classPath, [, manifestFilePath]]])

## Paramètres

jarFilePath

  Une chaine de caractères, contenant le chemin d'accès complet du fichier JAR destination.

packageNames

  Une matrice de chaines de caractères, définissant les noms des packages Java à construire et à stocker dans le fichier JAR.

sourcePaths

  Une matrice de chaines de caractères, contenant les chemins d'accès des répertoires contenant les sources Java.

classPaths

  Une matrice de chaines de caractères (optionelle), qui contient les chemins d'accès des dépendences de compilation.

manifestFilePath

  Une chaine de caractères, (optionelle), contenant le chemin d'accès complet d'un fichier manifeste à inclure dans le fichier JAR.

## Description

`ilib_build_jar` étend au language Java la fonction ilib_build, qui sert à construire des libraries C/C++/Fortran. En d'autres termes, `ilib_build_jar` permet de construire des librairies Java à partir de sources Java. En Java, une librairie est un fichier JAR (archive Java, dont l'extension est `.jar`), qui contient des packages Java compilés (un package Java regroupe un ensemble de classes) et un fichier manifeste, qui décrit le contenu du fichier JAR.

`ilib_build_jar` fonctionne comme suit. Tous les fichiers sources Java trouvés dans les chemins de répertoires donnés par l'argument `sourcePaths` sont compilés. Ensuite le fichier JAR cible dont le chemin est donné par l'argument `jarFilePath` est créé à partir de toutes les classes compilées correspondant aux packages déclarés dans l'argument `packageNames`. `ilib_build_jar` se base sur la fonction jcompile pour la compilation et sur jcreatejar pour la création d'archive JAR. Aucun autre outil externe supplémentaire n'est requis.

Rappelons quelques informations à propos des packages Java, essentielles pour utiliser `ilib_build_jar`. Les pakages Java sont structurés de façon hiérarchique, et Java impose que l'emplacement des fichiers sources correspond à la hiérarchie des packages, par exemple un package portant le nom monpackage doit être stocké dans un répertoire du même nom. La convention est qu'un fichier JAR contient habituellement une seule hiérarchie de packages Java, et son nom de fichier correspond au nom de package racine, qui sera de type `org.company.software.package`. `ilib_build_jar` peut être utilisée pour créer un fichier JAR contenant plusieurs hiérarchies de packages Java, avec un nom de fichier arbitraire. Les seules obligations sont qu'un nom de package au moins doit être déclaré à `ilib_build_jar`, et que chacune des classes Java doit appartenir à un package.

Les dépendances nécessaires pour la compilation peuvent être déclarées dans l'argument `classPaths`. Cela peut être des chemins complets à des fichiers JAR contenant des packages Java, ou à des répertoires contenant des classes Java compilées.

On peut aussi spécifier un chemin d'accès à un fichier manifeste, via l'argument `manifestFilePath`, dont les données seront stockées dans le fichier JAR, dans le fichier `MANIFEST.MF`, dans le sous-répertoire `META-INF`. Si le fichier manifeste n'est pas spécifié ou n'existe pas, un manifeste sera créé par défaut. Note: si on spécifie un manifeste, celui doit contenir un attribut de version, autrement le manifeste dans le fichier JAR risque d'être vide.

## Exemples

    // Exemple pour ilib_build_jar

    // Crée les sources du package org.scilab.test.mypackage package dans TMPDIR
    packageName = 'org.scilab.test.mypackage';
    packageSrcPath = fullfile(TMPDIR, packageName);

    // Crée un fichier source du package (dans le répertoire org/scilab/test/mypackage)
    function addJavaSourceToPackage(className, packageName)
        packagePath = strsubst(packageName, '.', filesep());
        packagePath = fullfile(packageSrcPath, packagePath);
        mkdir(packagePath);
        filePath = fullfile(packagePath, className + '.java');

        sourceCode = [msprintf('package %s;', packageName); ..
            msprintf('public class %s {}\n', className);
            ];
        fd = mopen(filePath, 'wt');
        mputl(sourceCode, fd);
        mclose(fd);
    endfunction

    // Ajoute les classes 'Foo' and 'bar.Bar' au package
    addJavaSourceToPackage('Foo', packageName);
    addJavaSourceToPackage('Bar', packageName + '.bar');

    // Construit le package
    jarFilePath = fullfile(TMPDIR, packageName + '.jar');
    ilib_build_jar(jarFilePath, packageName, packageSrcPath);

    // Import et teste la package
    javaclasspath(jarFilePath);
    jimport org.scilab.test.mypackage.Foo;
    foo = Foo.new();
    jimport org.scilab.test.mypackage.bar.Bar;
    bar = Bar.new();

## Voir aussi

- jcompile
- jcreatejar
- javaclasspath

## Historique

5.5.0
Fonction introduite.