| Name | toyboxpy JSON |
| Version |
1.3.1
JSON |
| download |
| home_page | None |
| Summary | A Lua, C and asset dependency manager for the Playdate SDK |
| upload_time | 2024-01-05 08:20:18 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | None |
| keywords |
package
package management
playdate
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# toybox.py
[](https://spdx.org/licenses/MIT.html) [](https://python.org) [](https://pypi.org/project/toyboxpy)
A **Lua**, **C** and asset dependency manager for the [**Playdate**](https://play.date) **SDK**.
**toybox.py** is a Python port of [Jeremy McAnally](https://github.com/jm)'s toybox app. **toybox.py** lets you easily use, create and share third party libraries, called **toyboxes**, for any **Playdate** project. It handles all dependencies between **toyboxes** automatically and provides precise versioning for each **toybox**.
Some **toyboxes** may provide **C** code, some may provide **Lua** code or **Lua** extensions written in **C** and some may provide just assets. Some **toyboxes** may provide all three or only two of these, it's completely up to the **toybox** creator and maintainer.
The main repo for the project is on [**codeberg**](https://codeberg.org/DidierMalenfant/toybox.py).
Playdate is a registered trademark of [**Panic**](https://panic.com).
-----
**Table of Contents**
- [Installation](#installation)
- [Usage](#usage)
- [Using Lua toyboxes](#using-lua-toyboxes)
- [Using C toyboxes](#using-c-toyboxes)
- [Creating your own toyboxes](#creating-your-own-toyboxes)
- [License](#license)
### Installation
**toybox.py** is a pure Python project. It requires at least [Python](https://python.org) 3.7 and access to the [git](https://git-scm.com) command line tool. Make sure you have a [supported version](http://didier.malenfant.net/blog/nerdy/2022/08/17/installing-python.html) of **Python** before proceeding.
You can install **toybox.py** by typing the following in a terminal window:
```console
pip install toyboxpy
```
### Usage
**toybox.py** supports various commands, sometimes with one or two extra arguments:
```console
toybox <options> <command> <arguments>
```
The following commands are supported:
```console
help <topic> - Show a help message. topic is optional (use 'help topics' for a list).
version - Get the current version.
license - Show the license for the app.
info - List your current dependencies.
add <name/url> <version> - Add a new dependency (version is optional).
remove <name/url> - Remove a dependency.
update <name/url> - Update a dependency or all dependencies if no argument is provided.
check - Check for updated toyboxes.
store <subcommand> - Get info about the toystore (use \'help store\' for more info).
set <name> <value> - Set a configuration value for this toybox.
setupMakefile - Setup a basic makefile project for using C toyboxes.
```
The following options are supported:
```console
--help/-h - Show a help message.
--force/-f - Forces the execution of some commands, even if things seem up to date.
--local/-l <folder> - Update the dependencies as local, if found in this folder.
--debug - Enable extra debugging information.
```
**toybox.py** should always be run from your project's root folder. Although it doesn't use and `git` commands directly on your project folder, some `git` commands that **toybox.py** uses do require that your project folder already be a `git` repo. A simple `git init` suffices. This also makes it easy for you to back-track any unwanted changes.
**toybox.py** creates and uses a local file at the root of your project's folder named `Boxfile`. You can use the `add` and `remove` commands to modify it.
#### Adding dependencies
The `add` command takes up to two arguments:
```console
toybox add <name/url> <version>
```
The first argument should either be name of a toybox, if it is listed in the **toystore**, the full url to a **git** repository which contains the **toybox** you would like to add, such as `https://codeberg.org/DidierMalenfant/modplayer.git`. For example, because `modplayer is on the **toystore**, any of the short forms below will point to the same repository:
``` console
toybox add modplayer
toybox add https://codeberg.org/DidierMalenfant/modplayer
toybox add codeberg.org/DidierMalenfant/modplayer
toybox add DidierMalenfant/modplayer
```
**toyboxes** do not need to be hosted on [Github](https://github.com) but, as shown above, if the server url is omitted then Github is assumed.
Adding a dependency with a `name` or `url` which already exists for your project will replace the `version` used for that dependency.
The `version` parameter is optional and allows you to select a specific or a range of versions for the **toybox** such as `1.4.12`. If no `version` argument is provided then the lastest version of the latest major version of the **toybox**'s repo, if available, is used.
You can also require a specific minor version with `1.4` or a specific major version with `1`. In that case, the latest version with the given minor or major version numbers will be used which allows a developer using your **toybox** to stay up to date with bug fixes or new features without risking an API change from breaking your project.
If you would like to fine tune your version requirement even more, you can instead use up to two comparaison operators in the `version` argument. For example `'>1.2.3 <=3.0.0'`. Keep in mind that, here too, valid [semver](https://semver.org) version numbers should be used. Major or minor versions can be still used in combination with comparaisons. For example, a version requirement like `'3 <3.9.0'` results in all versions higher or equal to `3.0.0` but less than `3.9.0`. Supported comparaison operators are `>`, `<`, `>=`, `<=`.
You can also specify the name of a branch when, for example, using a development version of a given **toybox**. In that case, the latest commit from that branch is used when updating.
``` console
toybox add modplayer develop
```
There may be times, like during development of a **toybox**, when you'll want to use a local version of a **toybox** instead of one found on a server. In order to do that, just replace `version` by the path to the local folder that contains your **toybox** and then use the `update` command. This path need to start with either `~` or `/`. In order to prevent you from committing files that come from a local **toybox** by mistake, using local **toyboxes** will also create a pre-commit hook that will prevent you from making any commits while local **toyboxes** are used.
Note that you can do this temporarily by using the `-l` option together with the `update` command described below.
On **macOS** and **linux**, the content of a local **toybox** is be soft-linked inside your project instead of copied. This way, any modifications you make during development will modify the actual local **toybox** directly. On **Windows**, the files from the local **toybox** are just copied over.
In order to restore everything after using local **toyboxes**, just add the regular version back and use the `update` command again.
#### Removing dependencies
You can remove a **toybox** with the remove command:
```console
toybox remove <name/url>
```
#### Updating dependencies
Once you've added or modified a dependency, you can update its content within your project by using the `update` command:
```console
toybox update <name/url>
```
If no `dependency` argument is used then all dependencies are updated.
**toybox** records the current version of any dependency installed in your project so keep in mind that this may modify the `Boxfile` for your project.
If you already have all your dependencies up to date then `update` will have no effect. If you need to force your dependencies to update, you can use the `-f` option.
```console
toybox -f update <name/url>
```
If you have local versions of **toyboxes** that you want to use instead of the ones found at the URL provided in the Boxfile, for example when you are testing changes on those **toyboxes** locally, you could modify each **toybox** entry separately but you can also use the `-l` option:
```console
toybox -l <folder> update
```
This will update all your dependencies and for any of those, if the **toybox** is found inside `folder` then this local version will be used instead. You can then simply use a regular `toybox update` to put everything back in place and use the online content of the repos again.
#### Checking for updates
You can check to see if any of the **toyboxes** you use have been updated by using the `check` command:
```console
toybox check
```
This will not modify anything within your project, it will just let you know if anything new is available for you.
### Using Lua toyboxes
Any **toybox** will be installed in a subfolder named `toyboxes` at the root folder of your project. If any of the **toyboxes** provides **Lua** code, a file named `toyboxes.lua` will be created in that folder. All you need to do to start using your **toyboxes** is import that file anywhere in your project.
Assuming you are using the standard [project structure](https://sdk.play.date/1.12.2/Inside%20Playdate.html#_structuring_your_project) suggested by the **Playdate SDK** and have your **Lua** source files in a subfolder named `source` then you can do this by adding this import statement in any file that uses the **toyboxes**:
```lua
import '../toyboxes/toyboxes.lua'
```
Note that due to a bug in the `pdc` app used by the **Playdate SDK** to process source files, the `.lua` extension is required here. Once this bug is fixed, this will no longer be needed.
### Using C toyboxes
Any **toybox** will be installed in a subfolder named `toyboxes` at the root folder of your project. If any of the **toyboxes** provides **C** code, a file named `toyboxes.mk` and a file named `toyboxes.h` will be created in that folder.
Assuming your makefile is in your project's root folder, you will need to include this makefile in your own before you include the **Playdate** SDK's common makefile:
```make
include toyboxes/toyboxes.mk
...
include $(SDK)/C_API/buildsupport/common.mk
```
You will then need to call the **toyboxes** init macro `REGISTER_TOYBOXES` during the `kEventInitLua` event and pass it a `PlaydateAPI*`:
```c
#include "toyboxes.h"
#include "pd_api.h"
int eventHandler(PlaydateAPI* playdate, PDSystemEvent event, uint32_t arg)
{
if(event == kEventInitLua) {
REGISTER_TOYBOXES(playdate)
}
return 0;
}
```
If you don't know how to or your project doesn't already use **C** extensions, you can use the `setupMakefile` command to create a bare bones makefile project, like the one above, in the current folder. Remember that makefile projects need to be built with `make` and not `pdc`.
### Using assets from toyboxes
If you want, or need, to access a **toybox**'s assets directly they will, if any, be located in a folder named `toybox_assets` inside the `source` folder of your project. The folder is organised by **toybox** URLs so, for example, an asset named `MyPic` in a **toybox** named `MyRepo` from user `Usernmame` on `github` will be located at
```
source/toybox_assets/github.com/Username/MyRepo/MyPic
```
Usually **toyboxes** should provide **Lua** methods to access their assets so you shouldn't need to do this.
### Using luacheck
If any of the **toyboxes** provide [`luacheck`](https://github.com/lunarmodules/luacheck) configuration in a [supported format](#adding-luacheck-globals), then **toybox.py** will generate a file named `luacheck.lua` inside the `toyboxes` folder. This file can be used to import this `luacheck` configuration in your project's `.luacheckrc`, for example, like this:
```lua
require "toyboxes/luacheck" (stds, files)
std = "lua54+playdate+toyboxes"
operators = {"+=", "-=", "*=", "/="}
```
Make sure to always run `luacheck` from the root folder of your project in order for these definitions to work correctly. For the time being, compound operators support is not part of the main branch of Luacheck. You can experiment with it by installing this [forked branch](https://codeberg.org/DidierMalenfant/luacheck/tree/compound-operators) of Luacheck.
### The toystore
The **toystore** is an online registry of known **toyboxes** and their `url` so that they can be referred to by only their names. It is located on [Github](https://codeberg.org/DidierMalenfant/toystore) and new **toyboxes** can be added to it by simply submitting a PR. This is purely for convenience though and there is no obligation that a **toybox** be added to the **toystore** for it to be freely available to anyone since you can always use its `url` directly.
To see a list of all available **toyboxes** in the **toystore** you can use the `store content` command:
```console
toybox store content
```
You can also get more information about a given toybox or open a browser to see the repo for a toybox with the `store info` and `store repo` commands:
```console
toybox store info pdbase
```
Information from the **toystore** is cached locally on your computer. You can use the `-f` option to force re-downloading this information.
### Adding the toybox powered badge
If your projects use **toyboxes**, you can let others know that they are [](https://codeberg.org/DidierMalenfant/toybox.py) by adding this badge to your `README.md` file:
```
[](https://codeberg.org/DidierMalenfant/toybox.py)
```
### Creating your own toyboxes
Of course the best part of **toybox.py** is that anyone can create, distribute and maintain their own **toyboxes** for others to use. All you need it a **git** repo (which can be located anywhere on the internet) and to make sure that some of your code is laid out in a way that **toybox** can process and understand.
For starters, the name of your **git** repo will be the name **toybox** uses for a lot of things. It's better not to use the name of an existing **toybox** as this could cause clashes with future **toybox.py** features (i.e. search for **toyboxes** on the **toyboxpy.io** website or add your **toybox** to a potential registry of **toyboxes**).
**toyboxes** can provide **Lua** methods, either written in **Lua** or in **C** as extensions to the **Lua** language, or **C** methods that can be used by others when writing their own **C** code for the **Playdate**. Your **toybox** can provide just one, two or all three of these types of extensions.
Versionning for **toyboxes** is done via tags in the git repo for your **toybox**. Those tags should be a valid [semver](https://semver.org) version and can optionally be prefixed by a `v`. For example `v2.3.0` is correct, `v2.3` is not. The most important part for users of your **toybox** is to make sure that you only fix issues when incrementing a patch version, that you only add new functionality when incrementing a minor version and that you always increment the major version when adding things to your **toybox** that may break things for your users (removing deprecated methods or changing the API for example).
It's usually a good idea, rather than provide a swiss-army knife type of **toybox**, to try and make sure your **toyboxes** provide just one service and do it well. Split different functionality into separate **toyboxes** so developers can only add the ones they need.
**toyboxes** can depend on other **toyboxes**. All you need is to add a `Boxfile` in the root folder of your **toybox** and it will be taken care of automatically when resolving dependencies. Be careful, during development for example, to not resolve that dependency directly in your project folder. You could end up committing the resulting **toyboxes** folder which would be redundant when others use your **toybox**. Instead you can use it as a local **toybox** in a test project.
A **Lua** **toybox** can depend on a **C** **toybox** and a **C** **toybox** can depend on another **C** **toybox**. You don't even need any extra import statements because any **Lua** **toyboxes** your **toybox** depends on should already be imported before your **toyboxe**'s import file is imported.
Try to make sure that **toyboxes** don't cross-depend on each other (**A** require **B** and **B** also requires **A**) as this is usually a sign of some API design issues and can complicate things in the long run.
#### Creating a Lua toybox
Creating a **Lua** **toybox** is as simple as adding one **Lua** file at the root to your project's repo or in a subfolder named `source` or `Source`. That file can be named `import.lua` or the same as your project and must contain all the import statements required to use your **toybox**. For example, the fictional `MyPdPi` **toybox**, if written in **Lua**, would contain one file named `MyPdPi.lua` which would look like this:
```lua
--
-- MyPdPi - Calculate Pi to an infinite number of decimals.
--
import "math"
import "picalc"
import "utils"
```
The source code itself in your **toybox** can be laid out any way you want (additional `Source` subfolder, etc...) as long as this file imports all the other files correctly.
If you wish to use a completely custom name or location for the **Lua** file **toybox** will import for your project, you can use the `set lua_import` command:
```console
toybox set lua_import mycustomfile.lua
```
This will create a `Boxfile` in your project, if one didn't already exist, and will set a configuration parameter for **toybox** to use that **Lua** file when importing your **toybox** instead of the default.
#### Creating a C toybox
Creating a **C** **toybox** is almost as simple and requires three things. First you need to create a makefile for your **toybox** in the root folder of your project and name it after your project. Once again, if the fictional `MyPdPi` **toybox** was written in **C**, it would contain one file named `MyPdPi.mk` which would look like this:
```make
#
# MyPdPi - Calculate Pi to an infinite number of decimals.
#
# -- Find out more about where this file is relative to the Makefile including it
_RELATIVE_FILE_PATH := $(lastword $(MAKEFILE_LIST))
_RELATIVE_DIR := $(subst /$(notdir $(_RELATIVE_FILE_PATH)),,$(_RELATIVE_FILE_PATH))
# -- Add us as an include search folder only if it's not already there
uniq = $(if $1,$(firstword $1) $(call uniq,$(filter-out $(firstword $1),$1)))
UINCDIR := $(call uniq, $(UINCDIR) $(_RELATIVE_DIR))
# -- Add our source files.
SRC := $(SRC) \
$(_RELATIVE_DIR)/MyPdPi/MyPdPi.c
```
The first section is very important and makes sure that the makefile is relocatable, i.e. can work no matter where the includer's makefile is located. The second part adds the root folder of your **toybox** as an include path. The last section adds the source files that need to be compiled for your **toybox**. Don't forget the `$(SRC)` on the first line to make sure that any previous sources files from other **toyboxes** are included.
The use of `:=` instead of `=` is also very important here as it forces make to resolve the value right here and there, instead of when it is used because it could have been overwritten by another **toybox** at that point.
If you wish to use a completely custom name or location for the makefile **toybox** will import for your project, you can use the `set makefile` command:
```console
toybox set makefile subfolder/OtherMakefile
```
This will create a `Boxfile` in your project, if one didn't already exist, and will set a configuration parameter for **toybox** to use that **Lua** file when importing your **toybox** instead of the default.
Header files for your project should be located in a subfolder named after your project, in our case `MyPdPi` and it should contain at least an include header named after your project, i.e. `MyPdPi.h` which, at a minimum, looks like this:
```c
/*
* MyPdPi - Calculate Pi to an infinite number of decimals.
*/
#ifndef MYPDPI_H
#define MYPDPI_H
#include "pd_api.h"
// -- Globals
extern PlaydateAPI* pd;
// -- toybox registration function
void register_MyPdPi(PlaydateAPI* playdate);
#endif
```
If you wish to use a completely custom name or location for the include file **toybox** will import for your project, you can use the `set include_header` command:
```console
toybox set include_header Folder/OtherHeader.h
```
This will create a `Boxfile` in your project, if one didn't already exist, and will set a configuration parameter for **toybox** to use that **Lua** file when importing your **toybox** instead of the default.
As shown above, your **toybox** header file needs to declare at least one function and that's the function called during the `kEventInitLua` event. The name of that function needs to be `register_<toybox_name>` and take a `PlaydateAPI* playdate` as an argument. If you're registering extensions to the **Lua** language this is where that would take place.
You can also declare any other functions your **toybox** exposes or include any other header files that may be needed. If your **toybox** is just providing **C** code for other projects and doesn't require any particular initialisation you can leave this method empty or just grab the `PlaydateAPI*` for future use elsewhere in your code, like so:
```c
/*
* MyPdPi - Calculate Pi to an infinite number of decimals.
*/
#include "MyPdPi/MyPdPi.h"
// -- Globals
PlaydateAPI* pd = NULL;
// -- toybox registration function
void register_MyPdPi(PlaydateAPI* playdate)
{
pd = playdate;
}
```
#### Providing assets in your toybox
If your **toybox** uses or provides assets, they should be located in a folder named `assets` at the root of your **toybox** folder. This folder will be moved into the end-user's `source` folder during installation so that it can be accessible by `pdc` during compilation of the project. You will therefore need to use a specific path in order to reach those assets from your code.
For example, if our `MyPdPi` **toybox** contained an image named `MyPic.png` in `assets/images` and was available via a `github` repo named `MyRepo` from user `MyUsername` then accessing the asset can be done as follows:
```
image = playdate.graphics.image.new(`toybox_assets/github.com/MyUsername/MyRepo/images/MyPic`)
```
While this works when the code is internal to your **toybox**, when you need to provide assets to the end-user of your **toybox**, it is much more elegant to provide utility methods in order to access your assets, like this:
```
function MyPdPi.getMyPic()
return playdate.graphics.image.new(`toybox_assets/github.com/MyUsername/MyRepo/images/MyPic`)
end
```
That way they do not have to deal with the path to your asset. Check out the [FontSample](https://codeberg.org/DidierMalenfant/FontSample) sample **toybox** for an examples of how to do this.
You can override the subfolder used for your **toybox**'s assets by using the `set assets_sub_folder` command:
```console
toybox set assets_sub_folder My/Custom/Path
```
This will create a `Boxfile` in your project, if one didn't already exist, and will set a configuration parameter for **toybox** to use that subfolder inside the **toybox_assets** folder. This is **not recommended** to use for production **toyboxes** as is could cause name collisions. It can still be useful if you forked a **toybox** repo for development but want to still keep the assets' path the same as the original repo.
### Adding luacheck globals
You can provide [`luacheck`](https://github.com/lunarmodules/luacheck) configuration info in your **toybox** that others using it can automatically benefit from. It needs to be in a supported format for **toybox.py** to detect and use it.
Just create a file named `Luacheck.lua` and place it in a folder named 'luacheck' in your project's root folder. This file will contain list of `globals` or `read_globals` provided by your **toybox**:
```lua
-- Globals provided by MyPdPi.
return {
globals = {
MyPdPi = {
fields = {
super = {
fields = {
className = {},
init = {}
}
},
className = {},
init = {},
calculatePi = {}
}
}
}
}
```
The format of this file follows similar rules to `luacheck`'s `.luacheckrc` [config file](https://luacheck.readthedocs.io/en/stable/config.html).
You can also still use this file for your **toybox**'s itself by creating a `.luacheckrc` like this one in your **toybox**:
```lua
stds.MyPdPi = require "luacheck/Luacheck"
std = "lua54+playdate+MyPdPi"
operators = {"+=", "-=", "*=", "/="}
```
#### Adding your toybox to the toystore
If you want to make it easy for others to use your **toybox**, you can submit a PR to the **[toystore](https://codeberg.org/DidierMalenfant/toystore)** in order for them to be able to refer to your **toybox** simply by its name. Entries in the toystore are located in the file `toystore.toml` and are be in the following format:
```toml
[Plupdate]
url = "https://codeberg.org/DidierMalenfant/Plupdate"
description = "The playdate.update() manager."
author = "Didier Malenfant <coding@malenfant.net>"
license = "MIT"
```
Make sure that your entry is added in alphabetical order in the file and that the name you decided to use is unique, not too generic and descriptive.
#### Letting others know about your toybox
It's not required, but it's always a good idea, to add a word about **toybox.py** in the README.md of your **toybox** repo so developers know what it contains and how to use it:
```console
**MyPdPi** is a [**Playdate**](https://play.date) **toybox** which lets you calculate Pi to an infinite number of decimals.
You can add it to your **Playdate** project by installing [**toybox.py**](https://codeberg.org/DidierMalenfant/toybox.py), going to your project folder in a Terminal window and typing:
toybox add MyGitHubUsername/MyPdPi
toybox update
This **toybox** contains both **Lua** and **C** toys for you to play with.
```
You can also add a nice [](https://codeberg.org/DidierMalenfant/toybox.py) badge like this:
```
[](https://codeberg.org/DidierMalenfant/toybox.py)
```
Don't forget to also let us know about your **toyboxes** via social media (`#toyboxpy`, mentions or DM) so that we can spread the word too...
### License
**toybox.py** is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "toyboxpy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "package,package management,playdate",
"author": null,
"author_email": "Didier Malenfant <coding@malenfant.net>",
"download_url": "https://files.pythonhosted.org/packages/c5/bb/cc5d2ceece3efa7d56fa03f39f1cb90aa009b732a127bb23c8a1e0acb582/toyboxpy-1.3.1.tar.gz",
"platform": null,
"description": "# toybox.py\n\n[](https://spdx.org/licenses/MIT.html) [](https://python.org) [](https://pypi.org/project/toyboxpy)\n\nA **Lua**, **C** and asset dependency manager for the [**Playdate**](https://play.date) **SDK**.\n\n**toybox.py** is a Python port of [Jeremy McAnally](https://github.com/jm)'s toybox app. **toybox.py** lets you easily use, create and share third party libraries, called **toyboxes**, for any **Playdate** project. It handles all dependencies between **toyboxes** automatically and provides precise versioning for each **toybox**.\n\nSome **toyboxes** may provide **C** code, some may provide **Lua** code or **Lua** extensions written in **C** and some may provide just assets. Some **toyboxes** may provide all three or only two of these, it's completely up to the **toybox** creator and maintainer.\n\nThe main repo for the project is on [**codeberg**](https://codeberg.org/DidierMalenfant/toybox.py).\n\nPlaydate is a registered trademark of [**Panic**](https://panic.com).\n\n-----\n\n**Table of Contents**\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Using Lua toyboxes](#using-lua-toyboxes)\n- [Using C toyboxes](#using-c-toyboxes)\n- [Creating your own toyboxes](#creating-your-own-toyboxes)\n- [License](#license)\n\n### Installation\n\n**toybox.py** is a pure Python project. It requires at least [Python](https://python.org) 3.7 and access to the [git](https://git-scm.com) command line tool. Make sure you have a [supported version](http://didier.malenfant.net/blog/nerdy/2022/08/17/installing-python.html) of **Python** before proceeding.\n\nYou can install **toybox.py** by typing the following in a terminal window:\n\n```console\npip install toyboxpy\n```\n\n### Usage\n\n**toybox.py** supports various commands, sometimes with one or two extra arguments:\n\n```console\ntoybox <options> <command> <arguments>\n```\n\nThe following commands are supported:\n\n```console\nhelp <topic> - Show a help message. topic is optional (use 'help topics' for a list).\nversion - Get the current version.\nlicense - Show the license for the app.\ninfo - List your current dependencies.\nadd <name/url> <version> - Add a new dependency (version is optional).\nremove <name/url> - Remove a dependency.\nupdate <name/url> - Update a dependency or all dependencies if no argument is provided.\ncheck - Check for updated toyboxes.\nstore <subcommand> - Get info about the toystore (use \\'help store\\' for more info).\nset <name> <value> - Set a configuration value for this toybox.\nsetupMakefile - Setup a basic makefile project for using C toyboxes.\n```\n\nThe following options are supported:\n\n```console\n--help/-h - Show a help message.\n--force/-f - Forces the execution of some commands, even if things seem up to date.\n--local/-l <folder> - Update the dependencies as local, if found in this folder.\n--debug - Enable extra debugging information.\n```\n\n**toybox.py** should always be run from your project's root folder. Although it doesn't use and `git` commands directly on your project folder, some `git` commands that **toybox.py** uses do require that your project folder already be a `git` repo. A simple `git init` suffices. This also makes it easy for you to back-track any unwanted changes.\n\n**toybox.py** creates and uses a local file at the root of your project's folder named `Boxfile`. You can use the `add` and `remove` commands to modify it.\n\n#### Adding dependencies\n\nThe `add` command takes up to two arguments:\n\n```console\ntoybox add <name/url> <version>\n```\n\nThe first argument should either be name of a toybox, if it is listed in the **toystore**, the full url to a **git** repository which contains the **toybox** you would like to add, such as `https://codeberg.org/DidierMalenfant/modplayer.git`. For example, because `modplayer is on the **toystore**, any of the short forms below will point to the same repository:\n\n``` console\ntoybox add modplayer\ntoybox add https://codeberg.org/DidierMalenfant/modplayer\ntoybox add codeberg.org/DidierMalenfant/modplayer\ntoybox add DidierMalenfant/modplayer\n```\n\n**toyboxes** do not need to be hosted on [Github](https://github.com) but, as shown above, if the server url is omitted then Github is assumed.\n\nAdding a dependency with a `name` or `url` which already exists for your project will replace the `version` used for that dependency.\n\nThe `version` parameter is optional and allows you to select a specific or a range of versions for the **toybox** such as `1.4.12`. If no `version` argument is provided then the lastest version of the latest major version of the **toybox**'s repo, if available, is used.\n\nYou can also require a specific minor version with `1.4` or a specific major version with `1`. In that case, the latest version with the given minor or major version numbers will be used which allows a developer using your **toybox** to stay up to date with bug fixes or new features without risking an API change from breaking your project.\n\nIf you would like to fine tune your version requirement even more, you can instead use up to two comparaison operators in the `version` argument. For example `'>1.2.3 <=3.0.0'`. Keep in mind that, here too, valid [semver](https://semver.org) version numbers should be used. Major or minor versions can be still used in combination with comparaisons. For example, a version requirement like `'3 <3.9.0'` results in all versions higher or equal to `3.0.0` but less than `3.9.0`. Supported comparaison operators are `>`, `<`, `>=`, `<=`.\n\nYou can also specify the name of a branch when, for example, using a development version of a given **toybox**. In that case, the latest commit from that branch is used when updating.\n\n``` console\ntoybox add modplayer develop\n```\n\nThere may be times, like during development of a **toybox**, when you'll want to use a local version of a **toybox** instead of one found on a server. In order to do that, just replace `version` by the path to the local folder that contains your **toybox** and then use the `update` command. This path need to start with either `~` or `/`. In order to prevent you from committing files that come from a local **toybox** by mistake, using local **toyboxes** will also create a pre-commit hook that will prevent you from making any commits while local **toyboxes** are used.\n\nNote that you can do this temporarily by using the `-l` option together with the `update` command described below.\n\nOn **macOS** and **linux**, the content of a local **toybox** is be soft-linked inside your project instead of copied. This way, any modifications you make during development will modify the actual local **toybox** directly. On **Windows**, the files from the local **toybox** are just copied over.\n\nIn order to restore everything after using local **toyboxes**, just add the regular version back and use the `update` command again.\n\n#### Removing dependencies\n\nYou can remove a **toybox** with the remove command:\n\n```console\ntoybox remove <name/url>\n```\n\n#### Updating dependencies\n\nOnce you've added or modified a dependency, you can update its content within your project by using the `update` command:\n\n```console\ntoybox update <name/url>\n```\n\nIf no `dependency` argument is used then all dependencies are updated.\n\n**toybox** records the current version of any dependency installed in your project so keep in mind that this may modify the `Boxfile` for your project.\n\nIf you already have all your dependencies up to date then `update` will have no effect. If you need to force your dependencies to update, you can use the `-f` option.\n\n```console\ntoybox -f update <name/url>\n```\n\nIf you have local versions of **toyboxes** that you want to use instead of the ones found at the URL provided in the Boxfile, for example when you are testing changes on those **toyboxes** locally, you could modify each **toybox** entry separately but you can also use the `-l` option:\n\n```console\ntoybox -l <folder> update\n```\n\nThis will update all your dependencies and for any of those, if the **toybox** is found inside `folder` then this local version will be used instead. You can then simply use a regular `toybox update` to put everything back in place and use the online content of the repos again.\n\n#### Checking for updates\n\nYou can check to see if any of the **toyboxes** you use have been updated by using the `check` command:\n\n```console\ntoybox check\n```\n\nThis will not modify anything within your project, it will just let you know if anything new is available for you.\n\n### Using Lua toyboxes\n\nAny **toybox** will be installed in a subfolder named `toyboxes` at the root folder of your project. If any of the **toyboxes** provides **Lua** code, a file named `toyboxes.lua` will be created in that folder. All you need to do to start using your **toyboxes** is import that file anywhere in your project.\n\nAssuming you are using the standard [project structure](https://sdk.play.date/1.12.2/Inside%20Playdate.html#_structuring_your_project) suggested by the **Playdate SDK** and have your **Lua** source files in a subfolder named `source` then you can do this by adding this import statement in any file that uses the **toyboxes**:\n\n```lua\nimport '../toyboxes/toyboxes.lua'\n```\n\nNote that due to a bug in the `pdc` app used by the **Playdate SDK** to process source files, the `.lua` extension is required here. Once this bug is fixed, this will no longer be needed.\n\n### Using C toyboxes\n\nAny **toybox** will be installed in a subfolder named `toyboxes` at the root folder of your project. If any of the **toyboxes** provides **C** code, a file named `toyboxes.mk` and a file named `toyboxes.h` will be created in that folder.\n\nAssuming your makefile is in your project's root folder, you will need to include this makefile in your own before you include the **Playdate** SDK's common makefile:\n\n```make\ninclude toyboxes/toyboxes.mk\n\n...\n\ninclude $(SDK)/C_API/buildsupport/common.mk\n```\n\nYou will then need to call the **toyboxes** init macro `REGISTER_TOYBOXES` during the `kEventInitLua` event and pass it a `PlaydateAPI*`:\n\n```c\n#include \"toyboxes.h\"\n\n#include \"pd_api.h\"\n\nint eventHandler(PlaydateAPI* playdate, PDSystemEvent event, uint32_t arg)\n{\n if(event == kEventInitLua) {\n REGISTER_TOYBOXES(playdate)\n }\n\n return 0;\n}\n```\n\nIf you don't know how to or your project doesn't already use **C** extensions, you can use the `setupMakefile` command to create a bare bones makefile project, like the one above, in the current folder. Remember that makefile projects need to be built with `make` and not `pdc`.\n\n### Using assets from toyboxes\n\nIf you want, or need, to access a **toybox**'s assets directly they will, if any, be located in a folder named `toybox_assets` inside the `source` folder of your project. The folder is organised by **toybox** URLs so, for example, an asset named `MyPic` in a **toybox** named `MyRepo` from user `Usernmame` on `github` will be located at\n```\nsource/toybox_assets/github.com/Username/MyRepo/MyPic\n```\nUsually **toyboxes** should provide **Lua** methods to access their assets so you shouldn't need to do this.\n\n### Using luacheck\n\nIf any of the **toyboxes** provide [`luacheck`](https://github.com/lunarmodules/luacheck) configuration in a [supported format](#adding-luacheck-globals), then **toybox.py** will generate a file named `luacheck.lua` inside the `toyboxes` folder. This file can be used to import this `luacheck` configuration in your project's `.luacheckrc`, for example, like this:\n\n```lua\nrequire \"toyboxes/luacheck\" (stds, files)\n\nstd = \"lua54+playdate+toyboxes\"\n\noperators = {\"+=\", \"-=\", \"*=\", \"/=\"}\n```\n\nMake sure to always run `luacheck` from the root folder of your project in order for these definitions to work correctly. For the time being, compound operators support is not part of the main branch of Luacheck. You can experiment with it by installing this [forked branch](https://codeberg.org/DidierMalenfant/luacheck/tree/compound-operators) of Luacheck.\n\n### The toystore\n\nThe **toystore** is an online registry of known **toyboxes** and their `url` so that they can be referred to by only their names. It is located on [Github](https://codeberg.org/DidierMalenfant/toystore) and new **toyboxes** can be added to it by simply submitting a PR. This is purely for convenience though and there is no obligation that a **toybox** be added to the **toystore** for it to be freely available to anyone since you can always use its `url` directly.\n\nTo see a list of all available **toyboxes** in the **toystore** you can use the `store content` command:\n\n```console\ntoybox store content\n```\n\nYou can also get more information about a given toybox or open a browser to see the repo for a toybox with the `store info` and `store repo` commands:\n\n```console\ntoybox store info pdbase\n```\n\nInformation from the **toystore** is cached locally on your computer. You can use the `-f` option to force re-downloading this information.\n\n### Adding the toybox powered badge\n\nIf your projects use **toyboxes**, you can let others know that they are [](https://codeberg.org/DidierMalenfant/toybox.py) by adding this badge to your `README.md` file:\n\n```\n[](https://codeberg.org/DidierMalenfant/toybox.py)\n```\n\n### Creating your own toyboxes\n\nOf course the best part of **toybox.py** is that anyone can create, distribute and maintain their own **toyboxes** for others to use. All you need it a **git** repo (which can be located anywhere on the internet) and to make sure that some of your code is laid out in a way that **toybox** can process and understand.\n\nFor starters, the name of your **git** repo will be the name **toybox** uses for a lot of things. It's better not to use the name of an existing **toybox** as this could cause clashes with future **toybox.py** features (i.e. search for **toyboxes** on the **toyboxpy.io** website or add your **toybox** to a potential registry of **toyboxes**).\n\n**toyboxes** can provide **Lua** methods, either written in **Lua** or in **C** as extensions to the **Lua** language, or **C** methods that can be used by others when writing their own **C** code for the **Playdate**. Your **toybox** can provide just one, two or all three of these types of extensions.\n\nVersionning for **toyboxes** is done via tags in the git repo for your **toybox**. Those tags should be a valid [semver](https://semver.org) version and can optionally be prefixed by a `v`. For example `v2.3.0` is correct, `v2.3` is not. The most important part for users of your **toybox** is to make sure that you only fix issues when incrementing a patch version, that you only add new functionality when incrementing a minor version and that you always increment the major version when adding things to your **toybox** that may break things for your users (removing deprecated methods or changing the API for example).\n\nIt's usually a good idea, rather than provide a swiss-army knife type of **toybox**, to try and make sure your **toyboxes** provide just one service and do it well. Split different functionality into separate **toyboxes** so developers can only add the ones they need.\n\n**toyboxes** can depend on other **toyboxes**. All you need is to add a `Boxfile` in the root folder of your **toybox** and it will be taken care of automatically when resolving dependencies. Be careful, during development for example, to not resolve that dependency directly in your project folder. You could end up committing the resulting **toyboxes** folder which would be redundant when others use your **toybox**. Instead you can use it as a local **toybox** in a test project.\n\nA **Lua** **toybox** can depend on a **C** **toybox** and a **C** **toybox** can depend on another **C** **toybox**. You don't even need any extra import statements because any **Lua** **toyboxes** your **toybox** depends on should already be imported before your **toyboxe**'s import file is imported.\n\nTry to make sure that **toyboxes** don't cross-depend on each other (**A** require **B** and **B** also requires **A**) as this is usually a sign of some API design issues and can complicate things in the long run.\n\n#### Creating a Lua toybox\n\nCreating a **Lua** **toybox** is as simple as adding one **Lua** file at the root to your project's repo or in a subfolder named `source` or `Source`. That file can be named `import.lua` or the same as your project and must contain all the import statements required to use your **toybox**. For example, the fictional `MyPdPi` **toybox**, if written in **Lua**, would contain one file named `MyPdPi.lua` which would look like this:\n\n```lua\n--\n-- MyPdPi - Calculate Pi to an infinite number of decimals.\n--\n\nimport \"math\"\nimport \"picalc\"\nimport \"utils\"\n```\n\nThe source code itself in your **toybox** can be laid out any way you want (additional `Source` subfolder, etc...) as long as this file imports all the other files correctly.\n\nIf you wish to use a completely custom name or location for the **Lua** file **toybox** will import for your project, you can use the `set lua_import` command:\n\n```console\ntoybox set lua_import mycustomfile.lua\n```\n\nThis will create a `Boxfile` in your project, if one didn't already exist, and will set a configuration parameter for **toybox** to use that **Lua** file when importing your **toybox** instead of the default.\n\n#### Creating a C toybox\n\nCreating a **C** **toybox** is almost as simple and requires three things. First you need to create a makefile for your **toybox** in the root folder of your project and name it after your project. Once again, if the fictional `MyPdPi` **toybox** was written in **C**, it would contain one file named `MyPdPi.mk` which would look like this:\n\n```make\n#\n# MyPdPi - Calculate Pi to an infinite number of decimals.\n#\n\n# -- Find out more about where this file is relative to the Makefile including it\n_RELATIVE_FILE_PATH := $(lastword $(MAKEFILE_LIST))\n_RELATIVE_DIR := $(subst /$(notdir $(_RELATIVE_FILE_PATH)),,$(_RELATIVE_FILE_PATH))\n\n# -- Add us as an include search folder only if it's not already there\nuniq = $(if $1,$(firstword $1) $(call uniq,$(filter-out $(firstword $1),$1)))\nUINCDIR := $(call uniq, $(UINCDIR) $(_RELATIVE_DIR))\n\n# -- Add our source files.\nSRC := $(SRC) \\\n $(_RELATIVE_DIR)/MyPdPi/MyPdPi.c\n```\n\nThe first section is very important and makes sure that the makefile is relocatable, i.e. can work no matter where the includer's makefile is located. The second part adds the root folder of your **toybox** as an include path. The last section adds the source files that need to be compiled for your **toybox**. Don't forget the `$(SRC)` on the first line to make sure that any previous sources files from other **toyboxes** are included.\n\nThe use of `:=` instead of `=` is also very important here as it forces make to resolve the value right here and there, instead of when it is used because it could have been overwritten by another **toybox** at that point.\n\nIf you wish to use a completely custom name or location for the makefile **toybox** will import for your project, you can use the `set makefile` command:\n\n```console\ntoybox set makefile subfolder/OtherMakefile\n```\n\nThis will create a `Boxfile` in your project, if one didn't already exist, and will set a configuration parameter for **toybox** to use that **Lua** file when importing your **toybox** instead of the default.\n\nHeader files for your project should be located in a subfolder named after your project, in our case `MyPdPi` and it should contain at least an include header named after your project, i.e. `MyPdPi.h` which, at a minimum, looks like this:\n\n```c\n/*\n* MyPdPi - Calculate Pi to an infinite number of decimals.\n*/\n\n#ifndef MYPDPI_H\n#define MYPDPI_H\n\n#include \"pd_api.h\"\n\n// -- Globals\nextern PlaydateAPI* pd;\n\n// -- toybox registration function\nvoid register_MyPdPi(PlaydateAPI* playdate);\n\n#endif\n```\n\nIf you wish to use a completely custom name or location for the include file **toybox** will import for your project, you can use the `set include_header` command:\n\n```console\ntoybox set include_header Folder/OtherHeader.h\n```\n\nThis will create a `Boxfile` in your project, if one didn't already exist, and will set a configuration parameter for **toybox** to use that **Lua** file when importing your **toybox** instead of the default.\n\nAs shown above, your **toybox** header file needs to declare at least one function and that's the function called during the `kEventInitLua` event. The name of that function needs to be `register_<toybox_name>` and take a `PlaydateAPI* playdate` as an argument. If you're registering extensions to the **Lua** language this is where that would take place.\n\nYou can also declare any other functions your **toybox** exposes or include any other header files that may be needed. If your **toybox** is just providing **C** code for other projects and doesn't require any particular initialisation you can leave this method empty or just grab the `PlaydateAPI*` for future use elsewhere in your code, like so:\n\n```c\n/*\n * MyPdPi - Calculate Pi to an infinite number of decimals.\n */\n\n#include \"MyPdPi/MyPdPi.h\"\n\n// -- Globals\nPlaydateAPI* pd = NULL;\n\n// -- toybox registration function\nvoid register_MyPdPi(PlaydateAPI* playdate)\n{\n pd = playdate;\n}\n```\n\n#### Providing assets in your toybox\n\nIf your **toybox** uses or provides assets, they should be located in a folder named `assets` at the root of your **toybox** folder. This folder will be moved into the end-user's `source` folder during installation so that it can be accessible by `pdc` during compilation of the project. You will therefore need to use a specific path in order to reach those assets from your code.\n\nFor example, if our `MyPdPi` **toybox** contained an image named `MyPic.png` in `assets/images` and was available via a `github` repo named `MyRepo` from user `MyUsername` then accessing the asset can be done as follows:\n```\nimage = playdate.graphics.image.new(`toybox_assets/github.com/MyUsername/MyRepo/images/MyPic`)\n```\nWhile this works when the code is internal to your **toybox**, when you need to provide assets to the end-user of your **toybox**, it is much more elegant to provide utility methods in order to access your assets, like this:\n```\nfunction MyPdPi.getMyPic()\n return playdate.graphics.image.new(`toybox_assets/github.com/MyUsername/MyRepo/images/MyPic`)\nend\n```\nThat way they do not have to deal with the path to your asset. Check out the [FontSample](https://codeberg.org/DidierMalenfant/FontSample) sample **toybox** for an examples of how to do this.\n\nYou can override the subfolder used for your **toybox**'s assets by using the `set assets_sub_folder` command:\n\n```console\ntoybox set assets_sub_folder My/Custom/Path\n```\n\nThis will create a `Boxfile` in your project, if one didn't already exist, and will set a configuration parameter for **toybox** to use that subfolder inside the **toybox_assets** folder. This is **not recommended** to use for production **toyboxes** as is could cause name collisions. It can still be useful if you forked a **toybox** repo for development but want to still keep the assets' path the same as the original repo.\n\n### Adding luacheck globals\n\nYou can provide [`luacheck`](https://github.com/lunarmodules/luacheck) configuration info in your **toybox** that others using it can automatically benefit from. It needs to be in a supported format for **toybox.py** to detect and use it.\n\nJust create a file named `Luacheck.lua` and place it in a folder named 'luacheck' in your project's root folder. This file will contain list of `globals` or `read_globals` provided by your **toybox**:\n\n```lua\n-- Globals provided by MyPdPi.\n\nreturn {\n globals = {\n MyPdPi = {\n fields = {\n super = {\n fields = {\n className = {},\n init = {}\n }\n },\n className = {},\n init = {},\n calculatePi = {}\n }\n }\n }\n}\n```\n\nThe format of this file follows similar rules to `luacheck`'s `.luacheckrc` [config file](https://luacheck.readthedocs.io/en/stable/config.html).\n\nYou can also still use this file for your **toybox**'s itself by creating a `.luacheckrc` like this one in your **toybox**:\n\n```lua\nstds.MyPdPi = require \"luacheck/Luacheck\"\n\nstd = \"lua54+playdate+MyPdPi\"\n\noperators = {\"+=\", \"-=\", \"*=\", \"/=\"}\n```\n\n#### Adding your toybox to the toystore\n\nIf you want to make it easy for others to use your **toybox**, you can submit a PR to the **[toystore](https://codeberg.org/DidierMalenfant/toystore)** in order for them to be able to refer to your **toybox** simply by its name. Entries in the toystore are located in the file `toystore.toml` and are be in the following format:\n\n```toml\n[Plupdate]\nurl = \"https://codeberg.org/DidierMalenfant/Plupdate\"\ndescription = \"The playdate.update() manager.\"\nauthor = \"Didier Malenfant <coding@malenfant.net>\"\nlicense = \"MIT\"\n```\n\nMake sure that your entry is added in alphabetical order in the file and that the name you decided to use is unique, not too generic and descriptive.\n\n#### Letting others know about your toybox\n\nIt's not required, but it's always a good idea, to add a word about **toybox.py** in the README.md of your **toybox** repo so developers know what it contains and how to use it:\n\n```console\n**MyPdPi** is a [**Playdate**](https://play.date) **toybox** which lets you calculate Pi to an infinite number of decimals.\n\nYou can add it to your **Playdate** project by installing [**toybox.py**](https://codeberg.org/DidierMalenfant/toybox.py), going to your project folder in a Terminal window and typing:\n\n toybox add MyGitHubUsername/MyPdPi\n toybox update\n\nThis **toybox** contains both **Lua** and **C** toys for you to play with.\n```\nYou can also add a nice [](https://codeberg.org/DidierMalenfant/toybox.py) badge like this:\n\n```\n[](https://codeberg.org/DidierMalenfant/toybox.py)\n```\n\nDon't forget to also let us know about your **toyboxes** via social media (`#toyboxpy`, mentions or DM) so that we can spread the word too...\n\n### License\n\n**toybox.py** is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Lua, C and asset dependency manager for the Playdate SDK",
"version": "1.3.1",
"project_urls": {
"Bug Tracker": "https://codeberg.org/DidierMalenfant/toybox.py/issues",
"Documentation": "https://codeberg.org/DidierMalenfant/toybox.py#readme",
"Homepage": "https://codeberg.org/DidierMalenfant/toybox.py",
"Source Code": "https://codeberg.org/DidierMalenfant/toybox.py"
},
"split_keywords": [
"package",
"package management",
"playdate"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "09399c2ffe4f6de8541f9dd4253587b24ef1cb6769acd8965039391429d706b8",
"md5": "db7df42b593113dbc436993354e2ac9b",
"sha256": "477308e85f7bea9a1370952484d90598561b39c01c661bc60eb66ac4d0ab8269"
},
"downloads": -1,
"filename": "toyboxpy-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "db7df42b593113dbc436993354e2ac9b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 33128,
"upload_time": "2024-01-05T08:20:20",
"upload_time_iso_8601": "2024-01-05T08:20:20.468152Z",
"url": "https://files.pythonhosted.org/packages/09/39/9c2ffe4f6de8541f9dd4253587b24ef1cb6769acd8965039391429d706b8/toyboxpy-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c5bbcc5d2ceece3efa7d56fa03f39f1cb90aa009b732a127bb23c8a1e0acb582",
"md5": "38a4f7eb29a8d0dd27ec03c40905eb27",
"sha256": "fea6d5bb0394747b024afa043bb7eadf465e269799c2ab40e4cde18a9b819a64"
},
"downloads": -1,
"filename": "toyboxpy-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "38a4f7eb29a8d0dd27ec03c40905eb27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 29920,
"upload_time": "2024-01-05T08:20:18",
"upload_time_iso_8601": "2024-01-05T08:20:18.320751Z",
"url": "https://files.pythonhosted.org/packages/c5/bb/cc5d2ceece3efa7d56fa03f39f1cb90aa009b732a127bb23c8a1e0acb582/toyboxpy-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-05 08:20:18",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": true,
"codeberg_user": "DidierMalenfant",
"codeberg_project": "toybox.py",
"lcname": "toyboxpy"
}
