haxelib

haxelib usage

Haxe is distributed with haxelib, a tool which enables developers to share their code and libraries into a common repository.

haxelib is a commandline tool, so you need to run it from a console. The following commands are available :

haxelib search word

Will list the projects which have either a name or description matching specified word.

haxelib info project-name

Will give you informations about a given project.

haxelib install project-name [version]

Will install the given project. You can optionally specify a specific version to be installed. By default, latest released version will be installed.

haxelib remove project-name [version]

Will remove a complete project or only a specified version if specified.

haxelib list

Will list all the installed projects and their versions. For each project, the version surrounded by brackets is the current one.

haxelib upgrade

Will upgrade all the installed projects to their latest version. This command prompts a confirmation for each upgradable project.

haxelib set project-name version

This will change the current version for a given project. The version must be already installed.

haxelib run project-name [arguments...]

This will run the given project if it provides a run script. Be careful to trust the project you are running since the script can damage your system.

Using an installed project from Haxe

Once a project is installed, you can simply use the Haxe compiler -lib parameter to be able to use it from your application :

haxe -lib project-name ...

By default, this is the current version of the project that is used. If you want to use a specific version of the project, add the version name separated by a : character.

haxe -lib project-name:version ...

Downloading behind a 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 #4077, modified 2008-08-29 01:07:54 by baurel