From 27ad3d80b6b4af8ac37900c8998e5699b6bb277e Mon Sep 17 00:00:00 2001
From: Lorenzo Cogotti <lcg@doublefourteen.io>
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.