From ac11fd59e141114ce6f6f2b012cbb21b4a3534d5 Mon Sep 17 00:00:00 2001 From: Lorenzo Cogotti Date: Tue, 16 Aug 2022 12:33:30 +0200 Subject: [PATCH] [README] Improve wording and consistency. --- README.md | 41 ++++++++++++++++++++++++++--------------- 1 file changed, 26 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 4c08b95..56b1bff 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,10 @@ It provides a structured approach to retrieve external libraries for your game p Lua knows some excellent dependency management system, like [LuaRocks](https://luarocks.org). -Though, they are not optimal for a game project, where: +Though, they are inconvenient 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). +* 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: @@ -26,10 +26,19 @@ LÖVE games have limited ways to manage external libraries: 2. 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. + * Introduce additional step to distribution phase. + * Many existing LÖVE libraries have no package manager support. -**crush** provides an alternative to this. +**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? @@ -37,22 +46,21 @@ 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. With `crush.lua` and `.lovedeps` in place, you can populate or refresh project dependencies by running: +3. Once you have `crush.lua` and `.lovedeps` in place, you can populate or refresh project dependencies by running: ```sh 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: +**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' ``` -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. +**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 @@ -63,7 +71,10 @@ The `.lovedeps` file is a regular Lua text file, containing a table where every ['dependency-name'] = "git-url" ``` -For example: +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 { @@ -84,8 +95,8 @@ For example: ## Philosophy -**crush** is somewhat opinionated and tied to its intended use-case. -It obeys the following general rules: +**crush** is somehow opinionated and tied to its intended use-case. +It obeys the following rules: `MUST`: @@ -117,4 +128,4 @@ provide some room for customization. ## License -See [LICENSE](LICENSE) for detailed information. +MIT, see [LICENSE](LICENSE) for detailed information.