mirror of https://gitea.it/1414codeforge/crush
[README] Describe crush in detail.
parent
ffd72490f7
commit
27ad3d80b6
@ -1,3 +1,110 @@
|
||||
# crush
|
||||
crush - The uncomplicated LÖVE external module system
|
||||
=====================================================
|
||||
|
||||
LÖVE external dependency 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.
|
||||
|
Loading…
Reference in New Issue