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](https://luarocks.org).
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:

```sh
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:

```lua
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:

```lua
dependency-name = "git-url"
```

For example:

```lua
{
    -- 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](https://github.com/Alloyed/loverocks) is a more involved project with the ambition to bring LuaRocks features to LÖVE.

## License

See [LICENSE](LICENSE) for license information.