[README] Improve wording and consistency.

master
Lorenzo Cogotti 2 years ago
parent 17e6ab6e17
commit ac11fd59e1

@ -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.

Loading…
Cancel
Save