crush/README.md

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

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

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

```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 your requirements, code should still be sufficiently hackable to
provide some room for customization.

## 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.