Lorenzo Cogotti 9c143655fc | ||
---|---|---|
.gitignore | ||
LICENSE | ||
README.md | ||
crush.lua |
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. 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:
-
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.
-
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:
- Copy the latest
crush.lua
into your project's root folder. - Create a
.lovedeps
file in the same directory, here you will list every dependency (more in the next section). - With
crush.lua
and.lovedeps
in place, you can populate or refresh project dependencies by running:
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:
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:
['dependency-name'] = "git-url"
For example:
{
-- Fetch lib/df-serialize from https://git.doublefourteen.io/lua/df-serialize
-- needs ['quote'] syntax due to '-'
['df-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",
-- Fetch lib/yui from https://git.doublefourteen.io/lua/yui
yui = "https://git.doublefourteen.io/lua/yui"
-- NOTE: Any dependency may also pull additional subdependencies,
-- these will also be cloned within lib/
}
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 is a more involved project with the ambition to bring LuaRocks features to LÖVE.
License
See LICENSE for detailed information.