From 27ad3d80b6b4af8ac37900c8998e5699b6bb277e Mon Sep 17 00:00:00 2001 From: Lorenzo Cogotti Date: Mon, 15 Aug 2022 18:54:20 +0200 Subject: [PATCH] [README] Describe crush in detail. --- README.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 109 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index bb9fc5a..50bc58c 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,110 @@ -# crush +crush - The uncomplicated LÖVE external module system +===================================================== -LÖVE external dependency system. \ No newline at end of file +**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.