Haxe is distributed with
haxelib, a tool which enables developers to share their code and libraries into a common repository. Before you can use haxelib you have to go through a easy setup
Access the http://lib.haxe.org website to view all the libraries available.
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 information 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 upgradeable 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
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 behind 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 information is mandatory:
- project name : this is the haxelib name of your project, it must contain 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 information will be available on the project page anyway.
- version : this is the information 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
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). Some native operating system zip methods (such as in OSX) may not work, so use the command line version:
zip -r target.zip dir/to/code
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
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 submitting, since once submitted, 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 exist 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 information unchanged) and submit it again.
If your project depends on another haxelib project, you can specify dependencies in the
<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
specific-project. Dependencies are set per-version, not per-project, so you can change dependencies of your project when submitting a new version.
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:
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.