Haxelib 3

Included with Haxe 3.0 is a new version of Haxelib - also version 3.0. For now, this behaves much the same as the old Haxelib, except that it will be pointing to a new repository. This means that with Haxe 3, you get the new haxe 3 libraries. And with Haxe 2.x, you can keep using Haxelib and not worry about your libraries being updated to the point where they are no longer compatible with Haxe 2 - so you can keep working on your legacy code.

Over time, the new Haxelib will get new features and a revamped website, while the old site and repo will be kept online for supporting legacy content.


Database reset

The biggest change is that the new haxelib points to a new haxelib repository. This allows us to separate libraries that were designed for Haxe 3 from those that work only with Haxe 2. As a user, this means that when you use the new Haxelib, (or simply, when using Haxe 3), only Haxe 3 libraries will be available for installation.

Developers will need to submit their libraries to the new repository for them to be available with Haxe 3.

If the library was already compatible with the Haxe 3 Release Candidate, the only required change will be to switch from using "haxelib.xml" to "haxelib.json". See "Legacy Support" below for more info about how the old repo, webiste and command line tool will continue to function.

JSON instead of XML

Packaged haxelibs previously had a "haxelib.xml" file which defined information about the project and the current version. With haxelib 2, we are requiring you to packages to use JSON instead, because the mapping to Haxe is more natural, and this will make writing tools and helpers even easier.

  "name": "useless_lib",
  "url" : "https://github.com/jasononeil/useless/",
  "license": "MIT",
  "tags": ["cross", "useless"],
  "description": "This library is useless in the same way on every platform",
  "version": "1.0.0",
  "releasenote": "Initial release, everything is working correctly",
  "contributors": ["Juraj","Jason","Nicolas"],
  "dependencies": {
    "tink_macros": "",
    "nme": "3.5.5"

To help speed up conversion, here is a Online Tool or you can use "haxelib convertxml" to convert a "haxelib.xml" in the current directory to a "haxelib.json".

Semantic versioning

To help haxelib have more intelligent dependency management, we are enforcing a set format for version numbers on haxelibs. The format is a simplified version of SemVer, and goes like this:


The basic rules:

  • Major versions are incremented when you break backwards compatibility - so old code will not work with the new version of the library.
  • Minor versions are incremented when new features are added.
  • Patch versions are for small fixes that do not change the public API, so no existing code should break.
  • When a minor version increments, the patch number is reset to 0. When a major version increments, both the minor and patch are reset to 0.


"0.0.1" // A first release.  Anything with a "0" for the major version is subject to change in the next release - no promises about API stability!
"0.1.0" // Added a new feature!   Increment the minor version, reset the patch version
"0.1.1" // Realised the new feature was broken.  Fixed it now, so increment the patch version
"1.0.0" // New major version, so increment the major version, reset the minor and patch versions.   You promise your users not to break this API until you bump to 2.0.0
"1.0.1" // A minor fix
"1.1.0" // A new feature
"1.2.0" // Another new feature
"2.0.0" // A new version, which might break compatibility with 1.0.  Users are to upgrade cautiously.

If this release is a preview (Alpha, Beta or Release Candidate), you can also include that, with an optional release number:



"1.0.0-alpha"   // The alpha of 1.0.0 - use with care, things are changing!
"1.0.0-alpha.2" // The 2nd alpha
"1.0.0-beta"    // Beta - things are settling down, but still subject to change.
"1.0.0-rc.1"    // The 1st release candidate for 1.0.0 - you shouldn't be adding any more features now
"1.0.0-rc.2"    // The 2nd release candidate for 1.0.0
"1.0.0"         // The final release!  

This versioning system will allow for more fine grained control over library versions that you specify in your hxml file, and will also allow libraries to more intelligently define what versions of other libraries they depend on. At the time of writing, haxelib still only supports exact dependency matching, but more advanced matching (where the latest compatible version is selected) will be included soon.

Haxelib self updating

New versions of Haxelib can now be released independent of the Haxe compiler. To update haxelib, run:

haxelib selfupdate

Please note that depending on your setup you may need administrative permissions to self-update.

Installation of a local ".zip" file

For installing a haxelib ".zip" file, you now use "haxelib local <filename>". The command is the same as the old "haxelib test", it is only the name that has changed.

haxelib local myLibrary.zip

Improvements to "haxelib git" and "haxelib dev"

To help manage dependencies better, "haxelib dev" and "haxelib git" both now look for the corresponding json file for each library, and will try to install any dependant libraries accordingly.

Haxelib git has also been modified to better support loading from a different branch or subdirectory of a repo. The new syntax is:

haxelib git library gitpath branch subdir


haxelib git h3d https://github.com/ncannasse/h3d                                         # default branch, top level dir
haxelib git detox git://github.com/jasononeil/detox.git master src/                      # master, src sub dir
haxelib git munit git://github.com/massiveinteractive/MassiveUnit.git mtask /core/src    # "mtask" branch, "/core/src" sub dir

Legacy Support (the old haxelib)

  • Any existing installations of haxelib 1.x will continue to work, and continue to point to the old repository, filled with Haxe 2 libraries.
  • To browse the old repository and website, go to http://lib.haxe.org/legacy/
  • To submit or update libraries for the legacy haxelib repository, continue to use the old haxelib binaries or neko files.


Going forward, Haxelib releases will be able to be released independently of Haxe releases, which should allow for faster development and inclusion of some new features.

Planned future improvements include:

  • A visual refresh for the website
  • Documentation for all uploaded versions of a library visible through the website
  • Stronger support for local, private or 3rd party haxelib servers


To help contribute (and make Haxe more powerful for everyone!) you can join the development on Github: https://github.com/back2dos/haxelib

Create new issues for feature proposals, and we are open to pull requests. If you have are implementing a major change, creating an issue to discuss it with other developers first is a good idea.

version #19349, modified 2013-05-08 15:57:29 by jason