Using haxelib

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.

Using haxelib

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.
  • haxelib dev project-name directory : this will set a development directory for the given project. To set project directory back to global location, run command and omit directory.

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 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>

note: "test" has been renamed to "local" in haxelib 1.04

Installing a library from git

It is possible to load a library from git rather than from haxelib. This is useful for using a more up to date development version, a fork of the original project, or for having a private library that you do not wish to post to haxelib.

  haxelib git <project-name> <git-clone-path> <branch> <subdirectory>

Where "subdirectory" is the folder in the repository that would normally be bundled and submitted to haxelib. For example, to install "xirsys_stdjs" from Skial's fork, you use:

  haxelib git xirsys_stdjs https://github.com/skial/stdjs.git haxelib

When you use "haxelib upgrade" any libraries that are installed using GIT will automatically pull the latest version.

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"/>
    <tag v="flash"/>
    <tag v="example"/>
    <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). MIT is allowed starting from Haxe 2.09
  • 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.
  • tag : you can choose any number of matching tags for your project, watch http://lib.haxe.org for commonly used tags
  • 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

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). 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 haxelib.xml.

Testing the package

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

  haxelib test <package-zip>

note: "test" has been renamed to "local" in haxelib 1.04

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.

Documentation

You can include the documentation for your project so it is hosted on haxelib. In order to do this, you must first build the XML documentation by using the following command :

haxe -xml haxedoc.xml my.pack.MyClass1 my.pack.MyClass2 ....

Make sure that all the classes of your project are either referenced from the commandline or referenced by another class which is compiled.

Once this is done, simply include the haxedoc.xml file inside your haxelib package, into the same directory as the haxelib.xml file. Once your project will be submitted, you will be able to browse its documentation on http://lib.haxe.org/d/[project]/[version].

You can submit or update documentation later. Each project version will have its own documentation.

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.

Extra Parameters

new in 2.10

If you add a file named extraParams.hxml to your library root (at the same level as haxelib.xml), these parameters will be automatically added to the compilation parameters when someone use your library with -lib.

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 64 bits sytem, the directory Windows64, Linux64, etc. are used instead. Please note that they will only be used if the NekoVM you are running is also 64 bit.

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.

Getting the directory of haxelib being called

When run.n is called from haxelib, the current working directory will be set to the library directory (eg. /usr/lib/haxe/lib/somelib/1,0/). The directory of haxelib being called will instead be passed as an extra argument, put at the end of the argument array. So to reset the cwd, use the following code:

var last:String = (new neko.io.Path(args[args.length-1])).toString();
var slash = last.substr(-1);
if (slash=="/"|| slash=="\\") 
    last = last.substr(0,last.length-1);
if (neko.FileSystem.exists(last) && neko.FileSystem.isDirectory(last)) {
    neko.Sys.setCwd(last);
}

version #19873, modified 2014-01-03 03:28:15 by jason