crush

crush - The uncomplicated LÖVE external module system.

crush is a minimalistic dependency-less package system for the LÖVE engine. It provides a structured approach to retrieve external libraries for your game project.

Why?

Lua knows some excellent dependency management system, like LuaRocks. Though, they are not optimal for a game project, where:

• External libraries should be packed along with the game for distribution.
• Packages are often small, and their code should be readily hackable by developers (package versions are not tremendously important).
• Depending on a complex package manager is undesireable.

LÖVE games have limited ways to manage external libraries:

1. Manually, directly copying external libraries in the game source tree.

   • Pulling latest changes in the library requires more copy-pasting.
   • Harder to use libraries if they depend on other libraries themselves.

2. Using a package manager during development, and carefully pack external libraries with the game manually upon distribution.

   • Adds a non-trivial step to distribution phase.
   • Many existing LÖVE libraries have no support for package managers.

crush provides an alternative to this.

How to use it?

To use crush follow these steps:

1. Copy the latest crush.lua into your project's root folder.
2. Create a .lovedeps file in the same directory, here you will list every dependency (more in the next section).
3. With crush.lua and .lovedeps in place, you can populate or refresh project dependencies by running:

lua crush.lua

crush will fetch the project's dependencies recursively, cloning them inside a lib subdirectory.

Thus you may use them comfortably in your code with a trivial require(), like this:

local serialize = require 'lib.serialize'

Meaning that crush flattens all dependencies inside the lib folder. This implies that common dependencies across different packages must be named and accessed consistently in the source code. A reasonable limitation given crush use-case.

The .lovedeps file

The .lovedeps file is a regular Lua text file, containing a table where every entry specifies a dependency:

['dependency-name'] = "git-url"

For example:

{
    -- Fetch lib/serialize from https://git.doublefourteen.io/lua/df-serialize
    serialize = "https://git.doublefourteen.io/lua/df-serialize",
    -- Fetch lib/gear from https://git.doublefourteen.io/lua/gear
    gear = "https://git.doublefourteen.io/lua/gear"
}

Philosophy

crush is somewhat opinionated and tied to its intended use-case. It obeys the following general rules:

MUST:

• Be Self-contained, only a single Lua file: crush.lua.
• Must only depend on Lua, LÖVE and git, expected to be available on any LÖVE developer machine.
• Do one thing: fetch the dependencies listed in the .lovedeps file.
• Be simple and predictable, integrating crush into a LÖVE game must be as intuitive as possible.
• Be hackable, its code must be reasonably trivial, understandable and adaptable.
• Enforce one way to do things, encouraging consistency.

MUST NOT:

• Give in to feature creep.
• Provide a centralized repository.
• Be completely general, its scope is limited to the average LÖVE game or library.
• Be entirely safe, there is no demand for checksum or strict versioning in crush use case.

SHOULD NOT:

• Break compatibility with older .lovedeps files.

If this does not meet your requirements, code should still be sufficiently hackable to provide some room for customization.

Similar projects

• LÖVERocks is a more involved project with the ambition to bring LuaRocks features to LÖVE.

License

See LICENSE for license information.