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