haxelib gebruiken

Haxe wordt gedistribueerd met haxelib, een tool welke developers in staat stelt hun code en libraries te delen in een gewone repository.

haxelib is een commandline tool, je dient het te draaien vanuit een console. De volgende commando's zijn beschikbaar:

  haxelib search word

Laat een lijst zien met projecten die ofwel in de naam of in de beschrijving het zoekwoord bevatten.

  haxelib info project-name

Geeft je informatie over het specifieke project

  haxelib install project-name [version]

Installeert het opgegeven project. Je kan optioneel een specifieke versie specificeren voor de install. Standaard wordt de laatste versie geïnstalleerd.

  haxelib remove project-name [version]

Verwijderd een compleet project of een gespecificeerde versie als die is opgegeven.

  haxelib list

Geeft een lijst met geïnstalleerde projecten en hun versies. Voor elk project is de huidige versie omgeven door brackets.

  haxelib upgrade

Upgrade al de geïnstalleerde projecten naar hun laatste versie. Dit commando prompt een bevestiging voor elk upgrade-baar project.

  haxelib set project-name version

Dit veranderd de huidige versie van opgegeven project. De versie moet al geïnstalleerd zijn.

  haxelib run project-name [arguments...]

Dit voert het project uit als het project in een uitvoer(run) script voorziet. Wees voorzichtig bij het vertrouwen van projecten aangezien het script je systeem kan beschadigen.

Gebruik maken van een geïnstalleerd project van Haxe

Als een project eenmaal is geinstalleerd, kan je simpel de -lib parameter van de Haxe compiler gebruiken om het te gebruiken in je applicatie :

  haxe -lib project-name ...

Standaard wordt de huidige versie voor het project gebruikt. Als je een andere versie wilt gebruiken voeg je de versie naam toe gescheiden door een : character.

  haxe -lib project-name:version ...

Downloaden achter een Firewall

There is no Web Interface for haxelib right now, but you can easily install an haxelib package from a ZIP file. This might be useful if you are behing a proxy/firewall that prevents haxelib from downloading the package. Simply browse http://lib.haxe.org/files to download the file/version you need, and save it on your local hard drive. You can then run the following command to install it :

  haxelib test <zip-file>

Creating a haxelib package

If you want to add your own project, you simply have to create a file named haxelib.xml. Here's an example :

<project name="myproject" url="http://myproject.org" license="GPL">
    <user name="mylogin"/>
    <description>This project is an example of an haxelib project</description>
    <version name="1.0">Initial release, everything is working correctly</version>
</project>

All the following informations are mandatory :

  • project name : this is the haxelib name of your project, it must contains at least 3 characters among the following : [A-Za-z0-9_-.] . In particular, no spaces are allowed.
  • project url : this is the url of your website. Please specify at least the repository URL of your project, or better the home page if you have any.
  • license : haxelib only permits open-source project to be added to the repository. The following license-strings are accepted : GPL, LGPL, BSD, Public (for Public Domain).
  • user : this is your user account name in the haxelib database. The first time the project is submitted, you will be asked to register for this account. User name has the same naming rules as the project name. Passwords are sent encrypted (MD5) on the server and only the encrypted version is stored. You can have several users for a given project if you want.
  • description : the description of your project. Try to keep it small, only 2-3 sentences explaining what it's doing. More informations will be available on the project page anyway.
  • version : this is the informations about the version you are submitting. The version name must match the same naming rules as the project name. A version description is needed, indicating the changes done. Try to keep it small as well.

Building a Package

Once your haxelib.xml file is written, you can create a package for your project. A Package consists in a ZIP file storing all your project release files and directories. For instance, here's an example of directory structure :

 |- myproject
     |- haxelib.xml
     |- my
        |- project
           |- MyClass.hx

This project includes only one single my.project.MyClass file. The myproject directory can be compressed into a ZIP to create a haxelib package ((Download the sample).

Usually, a user should be able to compile your sources by simply adding to the haxe commandline -cp path/to/myproject. Do NOT put the sources intended to be used by the end-user into a src package or another convention. For instance, if you don't have any package, the sources should be in the same directory as haxelib.xml.

Testing the package

Once your package is ready, you can test it by using

  haxelib test <package-zip>

Check that everything (both installation and usage) is working correctly before submiting, since once submited, a given version cannot be updated.

Submitting a Package

Once ready, you can submit a package by running the following command :

  haxelib submit myproject.zip

If the user name is unknown, you'll be first asked to register an account. If the user already exists, you will be prompted for your password.

If the project does not exists yet, it will be created, but no version will be added. You will have to submit it a second time to add the first released version.

If you want to modify the project url or description, simply modify your haxelib.xml (keeping version informations unchanged) and submit it again.

Dependencies

If your project depends on another haxelib project, you can specify dependencies in the haxelib.xml file :

<project name="myproject" url="http://myproject.org" license="GPL">
    ...
    <depends name="other-project"/>
    <depends name="specific-project" version="1.2"/>
</project>

For example, we specify here that this version of myproject will depends on latest other-project version and on the version 1.2 of specific-project. Dependencies are set per-version, not per-project, so you can change dependencies of your project when submitting a new version.

Runnable Project

If you include a precompiled Haxe/Neko run.n file in your project package (in the same directory where stays haxelib.xml) then users will be able to run your project by using the haxelib run command. This is useful if you want users to be able to do some post-install script that will configure some additional things on the system.

Including Neko Dlls

If your project is a Neko project which includes Neko DLLs (ndll files), then you need to store them in the ndll directory of your haxelib package, followed by the system name :

 |- myproject
     |- haxelib.xml
     |- my
     |  |- project
     |     |- MyClass.hx
     |- ndll
        |- Linux
        |   |- myproject.ndll
        |- Windows
           |- myproject.ndll

The following systems can be used : Windows, Linux, Mac and BSD. If a system directory does not exists when the project is used by the end-user, haxelib will display an error message telling that this project is not supported on his system.

For Mac, please provide universal binaries of your ndll files so they can be run on both Mac/PCC and Mac/Intel.

Please don't forget also add the sources of your ndll file as part of the package. Even if they are not needed to use your project, it's needed to include them as part of the release to keep everything open-source.

version #1220, modified 2008-05-06 22:42:19 by Folkert