Haxe Module Manager (hmm)

hmm is a small helper for haxelib that allows you to specify, install, and update project dependencies using lib.haxe.org libraries, git, mercurial, or dev (local path reference) libraries.

This exists because haxelib does not yet support specifying git, mercurial, or other non haxelib-based project dependencies in the haxelib.json, .hxml, etc. files. Once haxelib adds full git and hg support, this project can probably go away.

hmm relies on the new haxelib local repo support, for installing project-local Haxe libs in a .haxelib directory. See haxelib newrepo for more details on this. It also uses haxelib itself for actually installing libraries (both from lib.haxe.org and via git/hg/etc.).

Notes on "Funkin' Crew Edition" differences

A series of changes made internally at Funkin' Crew Inc. such as bugfixes, QoL, code cleanup. Ideally these can be merged into the base hmm!

Funkin' Crew Edition Usage

If you want to use the Funkin' Crew Edition of hmm

haxelib git hmm https://github.com/FunkinCrew/hmm.git funkin-patches
haxelib run hmm setup
hmm version # 3.1.0 Funkin' Crew Edition

Funkin' Crew Fixes

• When haxelib path returns an error when running hmm install or hmm reinstall, we just assume that the library wasn't installed correctly the first time, so we install it as if it was never installed.
• Fix for checking haxelib git remotes. Previous behaviour would take a ssh formed git remote url and an https formed git remote would be different, even if they lead to the same place. This affects users who might have a git config that automatically changes remote urls to ssh versions, and accomodates for them.
• Adds SHA1 to hmm version command
• Allow -q/--quiet to be passed through to the haxelib commands when using hmm reinstall

Installing hmm

> haxelib --global install hmm
> haxelib --global run hmm setup

• The --global flag is needed to make sure the tool is installed globally.
• The setup command creates aliases for ease of use:
  • on Linux/MacOS: creates a link to the hmm tool at /usr/local/bin/hmm
  • on Windows: creates a hmm.cmd script in %HAXEPATH%
• If you do not run setup, you can use the tool by running:

haxelib --global run hmm [command] [options]

rather than:

hmm [command] [options]

Example workflows

Installation

# Make sure hmm is installed (only needed once)
> haxelib --global install hmm
> haxelib --global run hmm setup

Self-update (update the global hmm install)

> hmm hmm-update

Self-removal (uninstall the global hmm install)

> hmm hmm-remove

New project setup and dependency installation

# Create your project directory
> mkdir my-project
> cd my-project

# initialize hmm and local .haxelib (create hmm.json and empty .haxelib/ directory in my-project/
> hmm init

# install some libraries from lib.haxe.org
> hmm haxelib utest
> hmm haxelib chrome-extension 45.0.1

# install some libraries via git repos
> hmm git thx.core git@github.com:fponticelli/thx.core master src
> hmm git mithril https://github.com/ciscoheat/mithril-hx master mithril

# install some libraries via mercurial repos
> hmm hg orm https://bitbucket.org/yar3333/haxe-orm default library

# view the hmm.json
> cat hmm.json
{
  "dependencies": [
    {
      "name": "chrome-extension",
      "type": "haxelib",
      "version": "45.0.1"
    },
    {
      "name": "mithril",
      "type": "git",
      "dir": "mithril",
      "ref": "master",
      "url": "https://github.com/ciscoheat/mithril-hx"
    },
    {
      "name": "orm",
      "type": "hg",
      "dir": "library",
      "ref": "default",
      "url": "https://bitbucket.org/yar3333/haxe-orm"
    },
    {
      "name": "thx.core",
      "type": "git",
      "dir": "src",
      "ref": "master",
      "url": "git@github.com:fponticelli/thx.core"
    },
    {
      "name": "utest",
      "type": "haxelib",
      "version": ""
    }
  ]
}

# view the local haxelib installs
> haxelib list
chrome-extension: [45.0.1]
mithril: git [dev:/Users/awhite/temp/haxelib-test-3/.haxelib/mithril/git/mithril]
orm: hg [dev:/Users/awhite/temp/my-project/.haxelib/orm/hg/library]
thx.core: git [dev:/Users/awhite/temp/haxelib-test-3/.haxelib/thx,core/git/src]
utest: [1.3.10]

Existing project setup if the project has an hmm.json file

# Clone a project that is using hmm
> git clone git@github.com:someuser/someproject
> cd someproject

# Install all libs from hmm.json
> hmm install

Dependency updates/changes

# Update dependencies from hmm.json that are not already installed at the specified version
> hmm reinstall

# Update all dependencies in hmm.json, even if they are already installed at the right version
> hmm reinstall -f

# Update a few dependencies, but only if the current install of each does not match the specified version in hmm.json
> hmm reinstall mylib1 mylib2

# Update a few dependencies, even if the current install of each matches the specified version in hmm.json
> hmm reinstall --force mylib1 mylib2

Project config file (hmm.json)

hmm requires a hmm.json file in the root of your project, which specifies the project dependencies (similar to npm's package.json).

Example hmm.json:

{
  "dependencies": [
    {
      "name": "thx.core",
      "type": "haxelib",
      "version": "0.34.0"
    },
    {
      "name": "thx.promise",
      "type": "git",
      "url": "git@github.com:fponticelli/thx.promise",
      "ref": "master",
      // Note: while it works, it's considered a bad practice to reference a branch
      // - better to reference a tag, commit, or other non-changing reference
      // Use `hmm lock` to automatically save/update the current hash ref in hmm.json
      "dir": "src"
    },
    {
      "name": "svg2ppt",
      "type": "git",
      "url": "git@github.com:pellucidanalytics/svg2ppt",
      "ref": "ae94bdc",
      "dir": "src"
    },
    {
      "name": "mithril",
      "type": "haxelib"
      // Note: while this works, it's considered a bad practice to reference a library
      // without specifying the version
      // Use `hmm lock` to automatically save/update the current havelib version in hmm.json
    },
    {
      // Note: "dev" dependencies are allowed for convenience, but not considered ideal,
      // because they do not specify any versioning, and requires others to have the
      // same local directory
      "name": "mylib",
      "type": "dev",
      "path": "/my/path/mylib"
    }
  ]
}

Each dependency is an object with the following keys:

• name - (required) the name of the Haxe library
• type - (required) one of haxelib, git, hg, or dev

For type haxelib, the following additional properties are used:

• version - (optional) the haxelib library version

For type git or mercurial, the following additional properties are used:

• url - (required) the git/hg URL
• ref - (optional) the git/hg ref (branch, commit, tag, etc.)
• dir - (optional) the root classpath directory

For type dev, the following additional properties are used:

• path - (required) the file system path to the code

Commands

• Almost all hmm commands should be run from your project root directory (where the hmm.json file should be located).
• See hmm help for information about specific commands.

Development Info

Build the code:

> haxe build.hxml

Release new version:

> git tag -a 3.4.5 -m 'Some message'
> $EDITOR haxelib.json # Set version
> submit