|
|
|
@ -1,58 +1,59 @@
|
|
|
|
|
crush - The uncomplicated LÖVE external module system
|
|
|
|
|
=====================================================
|
|
|
|
|
crush
|
|
|
|
|
=====
|
|
|
|
|
|
|
|
|
|
**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.
|
|
|
|
|
**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,
|
|
|
|
|
such as [LuaRocks](https://luarocks.org).
|
|
|
|
|
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.
|
|
|
|
|
* 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.
|
|
|
|
|
* 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 two ways to manage external libraries:
|
|
|
|
|
LÖVE games have limited ways to manage external libraries:
|
|
|
|
|
|
|
|
|
|
1. Manually, by direct copy of the external library's source code into the
|
|
|
|
|
game project.
|
|
|
|
|
1. Manually, directly copying external libraries in the game source tree.
|
|
|
|
|
|
|
|
|
|
* Pulling the latest changes in the library requires copy-pasting the latest version.
|
|
|
|
|
* Makes it harder to use libraries depending on other libraries themselves.
|
|
|
|
|
* Pulling latest changes in the library requires more copy-pasting.
|
|
|
|
|
* Harder to use libraries if they depend on other libraries themselves.
|
|
|
|
|
|
|
|
|
|
2. Using any available Lua package manager during development, and carefully
|
|
|
|
|
pack external libraries in the game manually upon distribution.
|
|
|
|
|
2. Using a package manager during development, and carefully
|
|
|
|
|
pack external libraries with 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.
|
|
|
|
|
* Adds a non-trivial step to distribution phase.
|
|
|
|
|
* Many existing LÖVE libraries have no support for package managers.
|
|
|
|
|
|
|
|
|
|
**crush** provides an alternative way to solve this.
|
|
|
|
|
**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` 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:
|
|
|
|
|
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 to within a `lib` subdirectory.
|
|
|
|
|
**crush** will fetch the project's dependencies recursively, cloning them inside a `lib` subdirectory.
|
|
|
|
|
|
|
|
|
|
You can thus use them comfortably in your code with a trivial `require()`, like this:
|
|
|
|
|
Thus you may 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.
|
|
|
|
|
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
|
|
|
|
|
|
|
|
|
@ -98,8 +99,8 @@ It obeys the following general rules:
|
|
|
|
|
* Break compatibility with older `.lovedeps` files.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If this does not meet some specific requirements,
|
|
|
|
|
|
|
|
|
|
If this does not meet your requirements, code should still be sufficiently hackable to
|
|
|
|
|
provide some room for customization.
|
|
|
|
|
|
|
|
|
|
## Similar projects
|
|
|
|
|
|
|
|
|
|