You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

113 lines
3.8 KiB
Markdown

crush
=====
2 years ago
**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.
* 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](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.