Wally has two pieces that work together: a command line tool named
wally and a registry server that hosts packages. Most users will only interact with the command line tool, but both are available in this repository.
With Aftman (preferred)
Aftman is the toolchain manager we recommend. You can use it to install Wally:
In your project (preferred)
aftman init aftman add UpliftGames/wally aftman install
Or install wally globally
aftman add --global UpliftGames/wally aftman install
Homebrew is also a convenient way to install wally! (only for MacOS/Linux)
brew install wally
Pre-built binaries are available for Windows, macOS, and Linux from the GitHub Releases Page for Wally.
It's straightforward to compile Wally from source. Wally requires Rust 1.51.0 or newer.
Clone the repository and use:
cargo install --locked --path .
Create a new, empty package.
wally install [--locked]
Installs all packages.
cargo XXX --locked, which will error if there is not an up-to-date lockfile. Intended for use on CI machines.
(locked is a planned feature and not yet implemented)
npm installwith no arguments
wally update [package-names]
Update packages recursively. By default, will update all packages. If any package names are given (in the form
scope/name@version-req), just those packages will be updated instead.
npm update(npm 7+, equivalent to
--depth 9999in npm 6.x and older)
wally publish [--token <token>]
Publish the current package.
wally login [--token <token>]
Log into an account to publish packages to a registry.
You can also directly provide a token via
wally login --token "$WALLY_AUTH_TOKEN".
Log out of a registry account.
wally package [--list] --output <path>
Package the current project as a zip file suitable for uploading to the package registry. Useful for adding entries to the registry and debugging what ends up in the blob that will be uploaded.
--list will output which files will be included instead of creating a zip file.
Prints the current project's manifest as a line of JSON. Used for adding entries to the package index.
wally search <query>
Search the registry to see what packages are available.
Wally aims to stand on the shoulders of giants. Decisions we make are in part backed up by looking at other package managers and other public documentation:
- So you want to write a package manager
- crates.io and Cargo from the Rust ecosystem
- PyPI, pip, pipenv, and Poetry from Python
The package manifest file describes a package and all of the packages it depends on. Package manifests are written in TOML and stored in a file named
Manifest files are written by humans. They can contain comments and formatting decisions that are tough to preserve with automatic editing tools. This should be okay -- editing a package manifest should be easy.
Manifest files define all necessary information about a package.
Here is an example package manifest, annotated with comments:
[package] # Package names are always "SCOPE/NAME" # They can include lowercase letters, numbers, and dashes. name = "lpghatguy/asink" # Descriptions are free-form. These will be used as part of package listings # and search results. description = "Asynchronous programming primitives" # Versions follow Semantic Versioning. # https://semver.org/ version = "2.0.7" # Contains an SPDX License Expression. # Licenses are required for publishing code to public registries. license = "MIT OR Apache-2.0" # The author list is a free-form list, but conventionally contains names and # email addresses. authors = ["Lucien Greathouse <email@example.com>"] # Packages belong to a "realm", which helps prevent using code in the wrong # context. For now, we have "server" and "shared" realms. # The server realm should only be used for packages which shouldn't be replicated. realm = "shared" # Wally supports multiple registries. # This feature can be used to have split public/private registries to # keep internal code private and isolated. registry = "https://github.com/upliftgames/wally-index" # You can also specify files to include or exclude from the package # By default gitignore files are respected and Wally won't include hidden # files/directories or packages downloaded by Wally. # include =  exclude = ["node_modules"] # Packages can be marked as private to prevent them from being published. private = true [dependencies] # Most dependencies will look like this. # # The name on the left is an alias. It defines what name we would like to # use to refer to this package. # # The value on the right will usually be a string of the form # "SCOPE/NAME@VERSION_REQ" # Versions are SemVer version requirements. The default behavior matches # Cargo, or npm with the `^` version specifier. Roact = "firstname.lastname@example.org" Promise = "email@example.com" [server-dependencies] # Dependencies in the server realm can be required here as shown above. # These are dependencies which should only ever exist on the server. [dev-dependencies] # Dev dependencies can be server or shared but are only needed during development. TestEZ = "firstname.lastname@example.org"
The lockfile contains the exact versions of each dependency that a project depends on. They're a critical feature that ensures that everyone who works on a game is getting the exact same version of every package.
Lockfiles are written in TOML and stored in a file named
wally.lock. They're human-readable, but are only written by tools. We've optimized the lockfile format for reading as well as diffing so that they're as easy to review as possible.
[[package]] name = "registry:lpghatguy/asink" version = "2.0.7" dependencies = [ "registry:roblox/roact", "registry:evaera/roblox-lua-promise", "registry:roblox/mono-thing", "git:https://github.com/Roblox/cool-thing.git", ] [[package]] name = "registry:evaera/roblox-lua-promise" version = "2.1.0" checksum = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" [[package]] name = "registry:roblox/mono-thing" version = "1.3.2" checksum = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" [[package]] name = "git:https://github.com/Roblox/cool-thing.git" rev = "foo" commit = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
Like many programming language package managers, Wally packages are published to a registry.
A Wally registry consists of two pieces, inspired by Cargo and crates.io:
- A Git repository containing a package index
- A registry API that handles downloading and publishing package contents
The official Wally registry is available at https://github.com/upliftgames/wally-index.
- Returns the contents of a package for installation
- Package contents are ZIP files
- Returns metadata for a package
- Query what packages are available on this registry
- Client will post a package tarball that is extracted and published from the server.