joshuacc / ahkpm

The AutoHotkey Package Manager

ahkpm - The AutoHotkey Package Manager.

AutoHotkey is a powerful tool for scripting automations on Windows, but managing dependencies for your scripts is painful. ahkpm brings modern package management to AutoHotkey, making it easier than ever to automate away the drudgery.

Documentation

Full documentation can be found at ahkpm.dev

Commands

Usage:
  ahkpm [flags]
  ahkpm [command]

Available Commands:
  cache       Manipulates the packages cache
  help        Help about any command
  init        Interactively create an ahkpm.json file in the current directory
  install     Installs specified package(s). If none, reinstalls all packages in ahkpm.json.
  list        List all installed packages and their versions
  update      Update package(s) to the latest version allowed by ahkpm.json
  version     Bumps the version in ahkpm.json.

Flags:
  -h, --help      help for ahkpm
  -v, --version   Display the version of ahkpm and AutoHotkey

Installation

To install ahkpm:

1. Go to the releases page and find the most recent version.
2. Download the ahkpm-{version}.msi file.
3. Open it on your Windows machine to launch the ahkpm installer.

Basic usage

1. Open the command line and navigate to the directory which will contain your AutoHotkey script.
2. Run ahkpm init and answer the prompts to create an ahkpm.json file
3. Run ahkpm install <package>@<version>
   • The package can be any github repository in the form: github.com/user/repo, or a shorthand in the form gh:user/repo
   • The version can be any of the following:
     • A valid semantic version such as 1.0.0
     • A valid semantic version range such as 2.x.x
     • The prefix tag: followed by the name of a tag in the package's repository, such as tag:beta2
     • The prefix branch: followed by the name of a branch in the package's repository, such as branch:main
     • The prefix commit: followed by the hash of a commit in the package's repository, such as commit:badcce14f8e828cda4d8ac404a12448700de1441
     • Omitting the version is not yet supported
4. Add #Include, %A_ScriptDir% to the top of your script to set the current directory as the context for subsequent includes
5. Add #Include, ahkpm-modules\github.com\user\repo\main-file.ahk to your script
6. You can now use the package's functionality within your AutoHotkey script!

Current limitations

ahkpm is being actively developed, but it is still a young project. As a result it has the following limitations.

• It only supports hosting and downloading of packages on GitHub, though other git hosts will be supported in the future.
• It does not (yet) handle problems with conflicting versions of transitive dependencies

If you'd like to help remedy these limitations, consider contributing!

Contributing to ahkpm

See the contribution guidelines

File formats

ahkpm.json

This file is where the user of ahkpm declares their dependencies and other package data.

{
  "version": "0.0.1",
  "description": "A brief description of what the package does",
  // URL for the package's git repository
  "repository": "github.com/user/my-project",
  // URL for the package's main website
  "website": "example.com",
  // The SPDX License identifier for the package's software license
  "license": "MIT",
  // URL for users to file bugs/issues for the package
  "issueTracker": "github.com/user/my-project/issues",
  // The primary file which users of the package should "Include" to use it in their scripts
  "include": "example.ahk",
  // Information about the primary author of the package
  "author": {
    "name": "joshuacc",
    "email": "",
    "website": "joshuaclanton.dev"
  },
  // Lists all dependencies along with the required version
  "dependencies": {
    "github.com/user/repo1": "1.0.0",
    "github.com/user/repo2": "tag:beta2",
    "github.com/user/repo3": "branch:main",
    "github.com/user/repo4": "commit:badcce14f8e828cda4d8ac404a12448700de1441"
  }
}

ahkpm.lock

This file is automatically generated by ahkpm and should not be edited.

{
  "lockfileVersion": 1,
  // This should exactly match ahkpm.json unless ahkpm.json has been manually edited
  "dependencies": {
    "github.com/joshuacc/mock-ahkpm-package-a": "branch:main",
  },
  "resolved": [
    {
      "name": "github.com/joshuacc/mock-ahkpm-package-a",
      "version": "branch:main",
      "sha": "c5b8f8d0d0d1e5c9a5f7f8b8b5c9a5f7f8b8b5c9a",
      "installPath": "ahkpm-modules/github.com/joshuacc/mock-ahkpm-package-a",
      "dependencies": {
          "github.com/joshuacc/mock-ahkpm-package-b": "^1.0.0"
      }
    },
    {
      "name": "github.com/joshuacc/mock-ahkpm-package-b",
      "version": "1.0.2",
      "installPath": "ahkpm-modules/github.com/joshuacc/mock-ahkpm-package-a/ahkpm-modules/github.com/joshuacc/mock-ahkpm-package-b",
      "sha": "c5b8f8d0d0d1e5c9a5f7f8b8b5c9a5f7f8b8b5c9a",
      "dependencies": {}
    }
  ]
}