crush/README.md

crush - The uncomplicated LÖVE external module system

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

Why?

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

• External libraries should be packed along with the game for distribution.
• External libraries are often small, and their code should be readily hackable by a developer (versioning is not tremendously important).
• Adding a dependency on a complex external package manager is undesireable.

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

1. Manually, by direct copy of the external library's source code into the game project.

   • Pulling the latest changes in the library requires copy-pasting the latest version.
   • Makes it harder to use libraries depending on other libraries themselves.

2. Using any available Lua package manager during development, and carefully pack external libraries in the game manually upon distribution.

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

crush provides an alternative way to solve 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 Lua text file in the same directory, here you will list every dependency.
3. With crush.lua and .lovedeps in place, you can populate, or refresh, the dependencies by running the command:

lua crush.lua

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

You can thus use them comfortably in your code with a trivial require(), like this:

local serialize = require 'lib.serialize'

This means that crush effectively flattens every dependency inside the project's lib folder.

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.
• 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 some specific requirements,

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.