lix - a dependable package manager for your Haxe projects

lix is a package manager that makes it easy for you to track dependencies used in your Haxe project, and to make sure everyone always has the right versions when they build your app.

• lix tracks everything in version control so you know exactly when and how a dependency changed. As a result:
  • lix helps you avoid "software erosion", so that when you come back to a project 6 months later on a different computer, you can still get things compiling exactly as they did last time you were working on it.
  • lix makes it easy to collaborate with other developers even when dependencies are changing regularly.
• lix works with all existing haxelibs, as well as dependencies hosted on GitHub or GitLab.
• lix lets you switch branches and update the dependencies much faster than haxelib.
• lix installs dependencies faster than haxelib.

The core proposition of lix is that all dependencies should be fully locked down and versioned, so that every state can be reliably replicated.

To track dependencies, lix leverages the conventions put forth by haxeshim. This means that for each dependency, there is a <libName>.hxml in the project's haxe_libraries folder. In addition to putting all required compiler arguments into a library's hxml, lix also leaves behind installation instructions that allow to redownload the exact same version on another machine. If you check out any particular state of a project, then lix download will download any missing library versions.

You can depend on lix to manage your haxe dependencies.

---

Contents

• Installation
• Usage
  • Downloading all dependencies
  • Adding a new dependency
  • Removing a dependency
  • Aliasing
  • HXML files
  • Version control
  • Local development
  • Scripting
• Concepts
• FAQ
• Help and support
• Contributing

---

Haxe Shim

Before we get started: lix is made to work on top of Haxe Shim. You can read more about it here, but essentially, you can think of it just normal Haxe with a slightly tweaked cli. What it does is to replace the tight coupling in the haxe toolchain in favor of simple conventions:

• decouple the haxe command from the haxe compiler (which are right now the very same thing) and instead use project specific configuration of the Haxe version, meaning that you can seamlessly have different Haxe versions in different projects on the same machine and also ensure that the same project will use the same Haxe version across different machines
• decouple Haxe from Haxelib (which are right now tied at the hip) and instead use project specific configuration of dependencies in a simple hxml-based format. Any tool capable of writing these hxmls can thus supply dependencies to the project. Moreover, this setup also ensures frictionless use of different dependency versions in different projects and reliable replication of dependency versions across separate machines.

Installation

lix is installed through npm (or yarn). If you don't have one of these installed, you can find out how to install NodeJS and NPM here.

To install lix:

npm install -g lix

After this you will have the commands lix, haxe, haxelib and neko available.

For each project you want to use lix for, you should create a "scope":

lix scope create
lix use haxe stable

This will create a ".haxerc" in the cwd, saying we should use the current stable Haxe version for this project. It will also tell Haxe Shim that this project should expect to find information about haxelibs in the "haxe_libraries" folder.

Usage

Downloading all dependencies

lix download

This will make sure all dependencies are installed and on the right versions. It will also fetch neko and the project specific haxe version.

You should use this after using git clone, git pull, git checkout and similar commands.

Adding a new dependency

lix install <scheme>:<library>

The schemes you can use include haxelib, github, gitlab, and http/https:

• haxelib:<name>[#<version>] - will get the library from haxelib, either the specific version or the latest. Use --haxelib-url <url> (either an https or http url) to use a different server consistently. You may also use haxelib://custom.server[:<port>]/<name>[#<version>], but in that case further dependencies will again be resolved against the official haxelib. If you leave the port unspecified, https assumed, otherwise http.
• github:<owner>/<repo>[#<branch|tag|sha>] - will get the library from GitHub, either master or a specific branch/tag/commit.
• gh:... an alias for github
• gitlab:<owner>/<repo>[#<branch|tag|sha>] - will get the library from GitLab. Use gitlab://custom.server/<owner>/<repo>[#<branch|tag|sha>] to get it from a server of your choice.
• git:<host>:/path/to/repo - where <host> is an ip, a qualified domain or even a name in your system's hosts file.
• http:<url> or https:<url> - will get the library from an arbitrary URL, pointing to a haxelib zip file... you MUST BE reasonably sure that the targeted resource NEVER changes. (For example, if the filename is "mylib-latest.zip", it will probably change. If it is "mylib-v1.0.0.zip", it is reasonably likely to not change).

Note that for github and gitlab you can specify credentials using the --gh-credentials and --gl-private-token parameters respectively. Be warned though that these credentials are then baked into the hxmls as well. Be very careful about using this option.

Because haxelib is a prominent source for stable versions, a shortcut is available: lix +lib <libname>. e.g. lix +lib hxcpp#3.4.188 is equivalent for lix install haxelib:hxcpp#3.4.188.

Removing a dependency

To remove a dependency simply delete the related .hxml file from your haxe_libraries folder.

This however won't remove the downloaded sources from the global cache. To do that you would have to delete it from ~/haxe/haxe_libraries or %AppData%\haxe\haxe_libraries.

Aliasing

You can always download a library under a different name and version, example:

lix install haxelib:tink_core as othername#1.2.3

You will find something like the following othername.hxml in your haxe_libraries:

# @install: lix --silent download "haxelib:tink_core#1.16.1" into tink_core/1.16.1/haxelib
-D othername=1.2.3
-cp ${HAXESHIM_LIBCACHE}/tink_core/1.16.1/haxelib/src

Hxml files

Once you've installed a dependency with lix and it exists in your haxe_libraries folder, you can add it to your haxe build (hxml file) with:

-lib mylibrary

where "mylibrary" has a valid file in haxe_libraries/mylibrary.hxml.

It's worth noting that we don't include the haxelib version in the hxml anymore, so doing this:

-lib mylibrary:1.0.0

is no longer accepted.

Version control

We recommend you add the entire haxe_libraries folder to your version control. For example, if you're using git:

git add haxe_libraries

Then every time you change a dependency with lix, you should commit those changes to git.

Every time you switch branches, pull, merge, or clone a new repo, if the files in "haxe_libraries" have changed, you should re-run:

lix download

(A fun fact: despite the name, lix download often doesn't have to download anything, especially if you've used those dependencies before, as they will be cached. This makes switching branches and syncing dependencies incredibly fast and painless).

Local development

If you develop your own haxelibs, you might be used to using haxelib dev to tell haxelib to use a local folder rather than a downloaded library while you develop your library, so that changes you make in the local folder are always used in the next build.

With lix, there is no command to do this, you just edit the relevant hxml file.

For example, change haxe_libraries/tink_core.hxml from:

# @install: lix --silent download "haxelib:tink_core#1.15.0" into tink_core/1.15.0/haxelib
-D tink_core=1.15.0
-cp ${HAXESHIM_LIBCACHE}/tink_core/1.15.0/haxelib/src

to:

# @install: lix --silent download "haxelib:tink_core#1.15.0" into tink_core/1.15.0/haxelib
-D tink_core=1.15.0
-cp /home/jason/workspace/tink_core/src/

When you do this, it will show up as a modified file in git. You should avoid commiting this change, as it won't work for anyone else who wants to use your project but doesn't have the exact same project in the exact same location.

Instead, once you've finished the work on your dependency, (even if it's a work in progress), push your changes to Github, and then use that:

lix install github:haxetink/tink_core#my_work_in_progress_branch

This way if anyone else wants to use your work-in-progress, they'll be able to.

Scripting

Lix supports running "haxe scripts" on either the interpreter or nodejs. The first argument must be something that looks like a class name (i.e. a dot path where the last part starts with an upper case letter, e.g. ExportAssets or tasks.export.Assets).

The class name resolution is as follows:

• attempt to find the class in the current scope's root (e.g. ExportAssets.hx or tasks/export/Assets/hx)
• attempt to find the class in the scripts sub directory of the current scope's root (e.g. scripts/ExportAssets.hx or scripts/tasks/export/Assets/hx) while using scripts as a class path
• if your project has a haxelib.json that defines a classPath, it is looked up therein. If there's a corresponding `