[README] Fix incomplete sentence, minor additional improvements.

This commit is contained in:
Lorenzo Cogotti 2022-08-15 19:08:30 +02:00
parent 27ad3d80b6
commit 1f030ef148
1 changed files with 27 additions and 26 deletions

View File

@ -1,58 +1,59 @@
crush - The uncomplicated LÖVE external module system
=====================================================
crush
=====
**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.
**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,
such as [LuaRocks](https://luarocks.org).
like [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.
* Packages are often small, and their code should be readily hackable by developers (package versions are not tremendously important).
* Depending on a complex package manager is undesireable.
LÖVE games have two ways to manage external libraries:
LÖVE games have limited ways to manage external libraries:
1. Manually, by direct copy of the external library's source code into the
game project.
1. Manually, directly copying external libraries in the game source tree.
* Pulling the latest changes in the library requires copy-pasting the latest version.
* Makes it harder to use libraries depending on other libraries themselves.
* Pulling latest changes in the library requires more copy-pasting.
* Harder to use libraries if they depend on other libraries themselves.
2. Using any available Lua package manager during development, and carefully
pack external libraries in the game manually upon distribution.
2. Using a package manager during development, and carefully
pack external libraries with 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.
* Adds a non-trivial step to distribution phase.
* Many existing LÖVE libraries have no support for package managers.
**crush** provides an alternative way to solve this.
**crush** provides an alternative to 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:
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:
```sh
lua crush.lua
```
**crush** will fetch the project's dependencies recursively, cloning them to within a `lib` subdirectory.
**crush** will fetch the project's dependencies recursively, cloning them inside a `lib` subdirectory.
You can thus use them comfortably in your code with a trivial `require()`, like this:
Thus you may 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.
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.
A reasonable limitation given **crush** use-case.
## The .lovedeps file
@ -98,8 +99,8 @@ It obeys the following general rules:
* Break compatibility with older `.lovedeps` files.
If this does not meet some specific requirements,
If this does not meet your requirements, code should still be sufficiently hackable to
provide some room for customization.
## Similar projects