1414codeforge/crush
1
0
Fork 0
mirror of https://codeberg.org/1414codeforge/crush.git synced 2025-06-05 21:49:49 +02:00
Code Packages Projects Releases Activity

[README] Improve wording and consistency.

Browse Source
This commit is contained in:
Lorenzo Cogotti
2022-08-16 12:33:30 +02:00
parent 17e6ab6e17
commit ac11fd59e1
1 changed files with 26 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
README.md
View File

@@ -10,10 +10,10 @@ It provides a structured approach to retrieve external libraries for your game p
Lua knows some excellent dependency management system, Lua knows some excellent dependency management system,
like [LuaRocks](https://luarocks.org). 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. * 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. * Depending on a complex package manager is undesireable.
LÖVE games have limited ways to manage external libraries: 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 2. Using a package manager during development, and carefully
pack external libraries with the game manually upon distribution. pack external libraries with the game manually upon distribution.
* Adds a non-trivial step to distribution phase. * Introduce additional step to distribution phase.
* Many existing LÖVE libraries have no support for package managers. * 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? ## 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. 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). 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 ```sh
lua crush.lua lua crush.lua
``` ```
**crush** will fetch the project's dependencies recursively, cloning them inside a `lib` subdirectory. **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:
Thus you may use them comfortably in your code with a trivial `require()`, like this:
```lua ```lua
local serialize = require 'lib.serialize' local serialize = require 'lib.serialize'
``` ```
Meaning that **crush** flattens all dependencies inside the `lib` folder. **crush** flattens every dependency in the `lib` folder.
This implies that common dependencies across different packages must be named and accessed consistently in the source code. 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. A reasonable limitation given **crush** use-case.
## The .lovedeps file ## 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" ['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 ```lua
{ {
@@ -84,8 +95,8 @@ For example:
## Philosophy ## Philosophy
**crush** is somewhat opinionated and tied to its intended use-case. **crush** is somehow opinionated and tied to its intended use-case.
It obeys the following general rules: It obeys the following rules:
`MUST`: `MUST`:
@@ -117,4 +128,4 @@ provide some room for customization.
## License ## License
See [LICENSE](LICENSE) for detailed information. MIT, see [LICENSE](LICENSE) for detailed information.