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](https://luarocks.org). Though, they are inconvenient for a game project, where: * External libraries should be packed along with the game for distribution. * Libraries are often small, and their code should be readily hackable by developers (library versions are not tremendously important). * Depending on a complex package manager is undesireable. LÖVE games have limited ways to manage external libraries: 1. 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. 2. Using a package manager during development, and carefully pack external libraries with the game manually upon distribution. * Introduce additional step to distribution phase. * Many existing LÖVE libraries have no package manager support. **crush** provides an alternative approach, offering the following features: * Fetch external libraries directly from their source code repository, ensuring the ability to pull, or even push, the latest changes from your project. * Automatically pack external libraries inside the project source tree, inside a well-known `lib` folder. * Resolves dependencies recursively, making possible for libraries that depend on other libraries, saving the developer all the manual dependency tracking. * Works automatically with most existing LÖVE libraries, since it directly uses `git` to clone their sources. * Does not require any complex package manager or native code, just a single Lua source file. * Does not require any centralized package repository to publish or fetch libraries. ## 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` file in the same directory, here you will list every dependency (more in the next section). 3. Once you have `crush.lua` and `.lovedeps` in place, you can populate or refresh project dependencies by running: ```sh lua crush.lua ``` **crush** fetches the project's dependencies recursively, cloning them inside a `lib` subdirectory. Hence, you may use them comfortably in your code with the usual `require()`, like this: ```lua local serialize = require 'lib.serialize' ``` **crush** flattens every dependency in the `lib` folder. This implies that libraries common to 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: ```lua ['dependency-name'] = "git-url" ``` The following example shows a `.lovedeps` file depending on three external libraries, named `df-serialize`, `gear` and `yui`, every dependency has a corresponding `git` repository URL. There dependency name is not required to match the actual repository name, but names **should** be consistent within the entire project, otherwise the same repository may be cloned several times under different names. ```lua { -- Fetch lib/df-serialize from https://codeberg.org/1414codeforge/df-serialize -- needs ['quote'] syntax due to '-' ['df-serialize'] = "https://codeberg.org/1414codeforge/df-serialize", -- Fetch lib/gear from https://codeberg.org/1414codeforge/gear gear = "https://codeberg.org/1414codeforge/gear", -- Fetch lib/yui from https://codeberg.org/1414codeforge/yui yui = "https://codeberg.org/1414codeforge/yui" -- NOTE: Any dependency may also pull additional subdependencies, -- these will also be cloned within lib/ } ``` ## Philosophy **crush** is somehow opinionated and tied to its intended use-case. It obeys the following 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](https://github.com/Alloyed/loverocks) is a more involved project aiming to bring LuaRocks features to LÖVE. ## License MIT, see [LICENSE](LICENSE) for details.