pesde-pkg/pesde
1
1
Fork 0
mirror of https://github.com/pesde-pkg/pesde.git synced 2025-05-04 02:23:51 +01:00
Code Issues Projects Releases Packages Wiki Activity

docs: write docs

Browse source
This commit is contained in:
LukaDev 2024-10-13 13:33:19 +02:00
parent ab07a2cd95
commit 2a5f54bfaf
17 changed files with 1474 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/.gitignore vendored
View file

@ -2,6 +2,7 @@
dist/
# generated types
.astro/
.vercel/
# dependencies
node_modules/

36
docs/astro.config.mjs
View file

@ -6,9 +6,6 @@ import vercel from "@astrojs/vercel/serverless"
// https://astro.build/config
export default defineConfig({
redirects: {
"/": "/guides/getting-started",
},
integrations: [
starlight({
title: "pesde docs",
@ -16,20 +13,21 @@ export default defineConfig({
github: "https://github.com/daimond113/pesde",
},
sidebar: [
{
label: "Intro",
items: [{ slug: "" }, { slug: "installation" }, { slug: "quickstart" }],
},
{
label: "Guides",
items: [
{
label: "Getting Started",
slug: "guides/getting-started",
},
],
autogenerate: { directory: "guides" },
},
{
label: "Reference",
autogenerate: {
directory: "reference",
},
autogenerate: { directory: "reference" },
},
{
label: "Registry",
autogenerate: { directory: "registry" },
},
],
components: {
@ -45,6 +43,20 @@ export default defineConfig({
content: "#F19D1E",
},
},
{
tag: "meta",
attrs: {
property: "og:image",
content: "/favicon-48x48.png",
},
},
{
tag: "meta",
attrs: {
name: "twitter:card",
content: "summary",
},
},
{
tag: "link",
attrs: {

41
docs/src/content/docs/guides/binary-packages.mdx Normal file
View file

@ -0,0 +1,41 @@
---
title: Using Binary Packages
description: Learn how to use binary packages.
---
A **binary package** is a package that contains a binary export.
Binary packages can be run like a normal program. There are several ways to use
binary packages with pesde.
## Using `pesde x`
The `pesde x` command can be used to run a one-off binary package. This is
useful for running a binary package without installing it or outside of a pesde
project.
```sh
pesde x pesde/hello
# Hello, pesde! (pesde/hello@1.0.0, lune)
```
## Installing a binary package
Binary packages can be installed using the `pesde add` and `pesde install`
commands.
This requires a `pesde.toml` file to be present in the current directory, and
will add the binary package to the `dependencies` section of the file.
```sh
pesde add pesde/hello
pesde install
```
This will add the binary package to your `PATH`, meaning that it can be run
anywhere!
```sh
hello
# Hello, pesde! (pesde/hello@1.0.0, lune)
```

170
docs/src/content/docs/guides/dependencies.mdx Normal file
View file

@ -0,0 +1,170 @@
---
title: Specifying Dependencies
description: Learn how to specify dependencies in your pesde project.
---
import { Aside, FileTree, LinkCard } from "@astrojs/starlight/components"
The `[dependencies]` section of your `pesde.toml` file is where you specify the
dependencies of your project.
pesde supports multiple types of dependencies.
## pesde Dependencies
The most common type of dependency are pesde dependencies. These are
dependencies on packages published to a [pesde registry](https://pesde.daimond113.com).
```toml title="pesde.toml"
[indices]
default = "https://github.com/daimond113/pesde-index"
[dependencies]
hello = { name = "pesde/hello", version = "^1.0.0" }
```
In this example, we're specifying a dependency on the `pesde/hello` package on
the official pesde registry with a version constraint of `^1.0.0`.
You can also add a dependency by running the following command:
```sh
pesde add pesde/hello
```
## Git Dependencies
Git dependencies are dependencies on packages hosted on a Git repository.
```toml title="pesde.toml"
[dependencies]
acme = { repo = "acme/package", rev = "main" }
```
In this example, we're specifying a dependency on the package contained within
the `acme/package` GitHub repository at the `main` branch.
You can also use a URL to specify the Git repository and a specific commit.
```toml title="pesde.toml"
[dependencies]
acme = { repo = "https://git.acme.local/package.git", rev = "aeff6" }
```
You can also specify a path if the package is not at the root of the repository.
<FileTree>
- acme/package.git
- pkgs/
- **foo/**
- pesde.toml
- ...
</FileTree>
```toml title="pesde.toml"
[dependencies]
foo = { repo = "acme/package", rev = "main", path = "pkgs/foo" }
```
The path specified by the Git dependency must either be a valid pesde package or
a [Wally][wally] package.
You can also add a Git dependency by running the following command:
```sh
# From Git URL
pesde add https://git.acme.local/package.git#aeff6
# From GitHub repository
pesde add gh#acme/package#main
```
## Wally Dependencies
Wally dependencies are dependencies on packages published to a
[Wally registry][wally]. Wally is a package manager for Roblox and thus Wally
dependencies should only be used in Roblox projects.
```toml title="pesde.toml"
[wally_indices]
default = "https://github.com/UpliftGames/wally-index"
[dependencies]
foo = { wally = "acme/package", version = "^1.0.0" }
```
In this example, we're specifying a dependency on the `acme/package` package
on the official Wally registry with a version constraint of `^1.0.0`.
<Aside type="note">
In order to get proper types support for Wally dependencies, you need to have
a [`sourcemap_generator` script](/reference/manifest#sourcemap_generator)
specified in your `pesde.toml` file.
</Aside>
You can also add a Wally dependency by running the following command:
```sh
pesde add wally#acme/package
```
[wally]: https://wally.run/
## Workspace Dependencies
Packages within a workspace can depend on each other. For example, if `foo`
and `bar` are both packages in the same workspace, you can add a dependency to
`bar` in the `foo/pesde.toml` file:
```toml title="foo/pesde.toml"
[dependencies]
bar = { workspace = "acme/bar", version = "^" }
```
You can also add a workspace dependency by running the following command:
```sh
pesde add workspace:acme/bar
```
<LinkCard
title="Workspaces"
description="Learn more about using workspaces in pesde."
href="/guides/workspaces/"
/>
## Peer Dependencies
Peer dependencies are dependencies that are not installed automatically when
used by another package. They need to be installed by the user of the package.
```toml title="pesde.toml"
[peer_dependencies]
foo = { name = "acme/foo", version = "^1.0.0" }
```
You can add a peer dependency by passing `--peer` to the `pesde add` command:
```sh
pesde add --peer acme/foo
```
## Dev Dependencies
Dev dependencies are dependencies that are only used during development. They
are not installed when the package is used as a dependency.
```toml title="pesde.toml"
[dev_dependencies]
foo = { name = "acme/foo", version = "^1.0.0" }
```
You can add a dev dependency by passing `--dev` to the `pesde add` command:
```sh
pesde add --dev acme/foo
```

6
docs/src/content/docs/guides/getting-started.md
View file

@ -1,6 +0,0 @@
---
title: Getting Started
description: pesde is very good
---
pesdies

80
docs/src/content/docs/guides/overrides.mdx Normal file
View file

@ -0,0 +1,80 @@
---
title: Overriding Dependencies
description: Learn how to override and patch dependencies in pesde.
---
import { Aside } from '@astrojs/starlight/components'
pesde has several ways to override or patch dependencies in your project.
## Dependency Overrides
Dependency overrides allow you to replace a dependency of a dependency with a
different version or package.
Let's say you have a project with the following dependencies:
```toml title="pesde.toml"
[dependencies]
foo = { name = "acme/foo", version = "^1.0.0" }
```
But `foo` depends on `bar` 1.0.0, and you want to use `bar` 2.0.0 instead. You
can override the `bar` dependency in your `pesde.toml` file:
```toml title="pesde.toml"
[dependencies]
foo = { name = "acme/foo", version = "^1.0.0" }
[overrides]
"foo>bar" = { name = "acme/bar", version = "^2.0.0" }
```
Now, when you run `pesde install`, `bar` 2.0.0 will be used instead of 1.0.0.
You can learn more about the syntax for dependency overrides in the
[reference](/reference/manifest#overrides).
## Patching Dependencies
Patching allows you to modify the source code of a dependency.
To patch a dependency, you can use the `pesde patch` and `pesde patch-commit`
commands.
Let's say you have the following dependency in your `pesde.toml` file:
```toml title="pesde.toml"
[target]
environment = "luau"
[dependencies]
foo = { name = "acme/foo", version = "^1.0.0" }
```
And you want to patch `foo` to fix a bug. You can run the following command:
```sh
pesde patch "acme/foo@1.0.0 luau"
# done! modify the files in the directory, then run `pesde patch-commit /x/y/z`
# to apply.
# warning: do not commit these changes
# note: the pesde.toml file will be ignored when patching
```
pesde will copy the source code of `foo` to a temporary directory, in this case
`/x/y/z`. You can then modify the files in this directory. Once you're done,
run `pesde patch-commit /x/y/z` to apply the changes.
This will create a patch within the `patches` directory of your project, and
add an entry to `[patches]`. Then, next time you run `pesde install`, the patch
will be applied to the dependency.
<Aside type="caution">
Make sure not to commit or stage the changes made in the temporary directory.
Otherwise pesde may not be able to create the patch correctly.
</Aside>

94
docs/src/content/docs/guides/publishing.mdx Normal file
View file

@ -0,0 +1,94 @@
---
title: Publishing Packages
description: Learn how to publish packages to the pesde registry.
---
## Configuration
Before you can publish a package, you must configure the required fields in your
`pesde.toml` file.
### `includes`
The `includes` field is a list of files and directories that should be included
in the package.
```toml
includes = [
"pesde.toml",
"README.md",
"LICENSE",
"init.luau",
]
```
### `target`
The `target` field defines the environment where the package can be run.
Here, you must also specify the `lib` and/or `bin` fields to indicate the path
of the exported library or binary.
```toml
[target]
environment = "luau"
lib = "init.luau"
```
#### Roblox
`bin` is not supported in Roblox packages. You must also specify a list of
`build_files`. These are the files that should be synced into Roblox. They are
passed to the `roblox_sync_config_generator` script.
For more information, see [Roblox](/guides/roblox).
```toml
[target]
environment = "roblox"
lib = "init.luau"
build_files = ["init.luau"]
```
## Authentication
Before you can publish a package, you must authenticate with your GitHub account.
```sh
pesde auth login
```
You will be given a code and prompted to open the GitHub authentication page in
your browser. You must enter the code to authenticate.
## Publishing
To publish a package, run the following command:
```sh
pesde publish
```
You will be prompted to confirm the package details before publishing.
Once a package is published, others will be able to install it. You may not
remove a package once it has been published. You may not publish a package with
an already existing version.
## Multi-target Packages
You may publish packages under the same name and version but with different
targets. This allows you to publish a package that can be used in multiple
environments.
For example, you may publish a package that can be used in both Roblox and
Luau environments by publishing two versions of the package, one for each
environment.
## Documentation
The `README.md` file in the root of the package will be displayed on the
[pesde registry website](https://pesde.daimond113.com/).
If you have a `docs` directory in the root of the package, they will be
hosted by pesde and be accessible on the pesde website.

36
docs/src/content/docs/guides/roblox.mdx Normal file
View file

@ -0,0 +1,36 @@
---
title: Roblox
description: Using pesde in a Roblox project.
---
pesde can be used in Roblox projects, however this requires some extra setup.
Namely, you need to specify a `roblox_sync_config_generator` script in order
to generate the adequate configuration for the sync tool you are using.
The [`pesde-scripts`](https://github.com/daimond113/pesde-scripts)
repository contains a list of scripts for different sync tools. If the tool
you are using is not supported, you can write your own script and submit a PR
to get it added.
These scripts are automatically cloned into the `~/.pesde/scripts` folder and
kept up to date when you use pesde.
## Usage with Rojo
[Rojo](https://rojo.space/) is a popular tool for syncing files into Roblox
Studio.
Running `pesde init` will prompt you to select a target, select
`roblox` or `roblox_server` in this case. This will setup the configuration
needed to use pesde in a project using Rojo.
## Usage with other tools
If you are using a different sync tool, you should look for it's scripts in the
pesde-scripts repository. If you cannot find them, you can write your own and
optionally submit a PR to help others using the same tool as you get started
quicker.
Scaffold your project with `pesde init`, select the `roblox` or `roblox_server`
target, and then replace the `.pesde/roblox_sync_config_generator.luau` script
with the one you want to use.

100
docs/src/content/docs/guides/workspaces.mdx Normal file
View file

@ -0,0 +1,100 @@
---
title: Workspaces
description: Learn how to use workspaces in pesde.
---
import { FileTree, LinkCard } from "@astrojs/starlight/components"
Workspaces allow you to work with multiple pesde projects within a single
repository. Packages within a workspace can depend on each other. And you can
run commands like install or publish on every package in the workspace at once.
Let's say you have a repository with the following structure:
<FileTree>
- pesde.toml
- pkgs/
- foo/
- pesde.toml
- ...
- bar/
- pesde.toml
- ...
</FileTree>
Within the root `pesde.toml` file, we can define a workspace:
```toml title="pesde.toml"
name = "acme/root"
version = "0.0.0"
private = "true"
workspace_members = ["pkgs/*"]
[target]
environment = "luau"
```
Now, each folder within the `pkgs/` directory is considered a package in the
workspace. You can run commands like `pesde install` or `pesde publish` from
the root of the repository to run them on every package in the workspace.
## Workspace Dependencies
Packages within a workspace can depend on each other. For example, if `foo`
depends on `bar`, you can add a dependency to `bar` in the `foo/pesde.toml` file:
```toml title="pkgs/foo/pesde.toml"
name = "acme/foo"
version = "1.0.0"
[dependencies]
bar = { workspace = "acme/bar", version = "^" }
```
Workspace dependencies are replaced with normal pesde dependencies when
publishing.
The `version` field can either contain `^`, `*`, `=`, `~`, or a specific version
requirement, such as `^1.0.0`. If you use `^`, `=`, or `~`, it will be replaced
with the version of the package in the workspace when publishing.
For example, if you had the following:
```toml title="pesde.toml"
[dependencies]
bar = { workspace = "acme/bar", version = "^" }
qux = { workspace = "acme/qux", version = "=" }
qar = { workspace = "acme/qar", version = "~" }
zoo = { workspace = "acme/zoo", version = "^2.1.0" }
baz = { workspace = "acme/baz", version = "*" }
```
If `bar`, `baz`, `qux`, `qar`, and `zoo` are all at version `2.1.5` in the
workspace, the `pesde.toml` file will be transformed into the following when
publishing.
```toml title="pesde.toml"
[dependencies]
bar = { name = "acme/bar", version = "^2.1.5" }
qux = { name = "acme/qux", version = "=2.1.5" }
qar = { name = "acme/qar", version = "~2.1.5" }
zoo = { name = "acme/zoo", version = "^2.1.0" }
baz = { name = "acme/baz", version = "*" }
```
A `target` field can be added to the `dependencies` table to specify a target
environment for the dependency.
```toml title="pesde.toml"
[dependencies]
bar = { workspace = "acme/bar", version = "^", target = "luau" }
```
<LinkCard
title="Specifying Dependencies"
description="Learn more about specifying dependencies in pesde."
href="/guides/dependencies/"
/>

32
docs/src/content/docs/index.mdx Normal file
View file

@ -0,0 +1,32 @@
---
title: What is pesde?
description: A package manager for the Luau programming language, supporting multiple runtimes including Roblox and Lune.
---
pesde is a package manager for the Luau programming language.
## Why use pesde?
When you write code, you often want to use libraries or frameworks that others
have written. Manually downloading and managing these can be cumbersome.
These libraries or frameworks can be distributed as packages. You can then
easily install and use these packages using pesde. pesde will automatically
download and manage the packages, and their dependencies, for you.
## Multi-target support
Luau can run in a lot of different places, such as on [Roblox][roblox], or in
[Lune][lune].
pesde is designed to work with all of these runtimes. Packages can publish
multiple versions of themselves, each tailored to a specific runtime.
[registry]: https://pesde.daimond113.com/
[roblox]: https://www.roblox.com/
[lune]: https://lune-org.github.io/docs
## The pesde registry
The [pesde registry][registry] is where anyone can publish their packages for
others to use.

89
docs/src/content/docs/installation.mdx Normal file
View file

@ -0,0 +1,89 @@
---
title: Installation
description: Install pesde
---
import { Aside, Steps, TabItem, Tabs } from "@astrojs/starlight/components"
## Prerequisites
pesde requires [Lune](https://lune-org.github.io/docs) to be installed on your
system in order to function properly.
You can follow the installation instructions in the
[Lune documentation](https://lune-org.github.io/docs/getting-started/1-installation).
## Installing pesde
<Steps>
1. Go to the [GitHub releases page](https://github.com/daimond113/pesde/releases/latest).
2. Download the corresponding archive for your operating system. You can choose
whether to use the `.zip` or `.tar.gz` files.
3. Extract the downloaded archive to a folder on your computer.
4. Open a terminal and locate the path of the extracted `pesde` binary.
<Tabs syncKey="os">
<TabItem label="Windows">
If you extracted the archive to `C:\Users\User\Downloads`, the path to the
`pesde` binary would be `C:\Users\User\Downloads\pesde.exe`.
You can then run the `self-install` command:
```ps
C:\Users\User\Downloads\pesde.exe self-install
```
pesde should now be installed on your system. You may need to restart your
computer for the changes to take effect.
</TabItem>
<TabItem label="Linux & macOS">
If you extracted the archive to `~/Downloads`, the path to the `pesde`
binary would be `~/Downloads/pesde`.
You must then add execute permissions and run the `self-install` command:
```sh
chmod +x ~/Downloads/pesde
~/Downloads/pesde self-install
```
pesde should now be installed on your system. You will need to update your
shell configuration file to add the pesde binary to your `PATH`
environment variable.
```sh title=".zshrc"
export PATH = "$PATH:/home/user/.pesde/bin"
```
You should then be able to run `pesde` after restarting your shell.
</TabItem>
</Tabs>
5. Verify that pesde is installed by running the following command:
```sh
pesde -v
```
This command should output the version of pesde that you installed.
</Steps>
<Aside type="caution">
It is not recommended to use toolchain managers (such as Rokit or Aftman) to
install pesde. You can use `pesde self-upgrade` if you need to update pesde.
If you need everyone to use the same version of pesde, you can use the
`pesde_version` field in `pesde.toml` to specify the version of pesde to use
for the current project.
</Aside>

142
docs/src/content/docs/quickstart.mdx Normal file
View file

@ -0,0 +1,142 @@
---
title: Quickstart
description: Start using pesde
---
import { FileTree } from "@astrojs/starlight/components"
Let's make a simple Luau program that uses the `pesde/hello` package to print
hello to the terminal.
## Scaffolding the project
In your terminal, run the following commands to create a folder and navigate
into it.
```sh
mkdir hello-pesde
cd hello-pesde
```
Then, we'll use `pesde init` to scaffold a new pesde project. The command will
ask you a few questions to set up the project. Our project will be named
`<username>/hello_pesde`, replace `<username>` with a username of your choice.
The name may only contain lowercase letters, numbers, and underscores. The
environment we're targeting is `luau`.
```sh
pesde init
# What is the name of the project? <username>/hello_pesde
# What is the description of the project? (leave empty for none)
# Who are the authors of this project? (leave empty for none, comma separated)
# What is the repository URL of this project? (leave empty for none)
# What is the license of this project? (leave empty for none) MIT
# What environment are you targeting for your package? luau
# Would you like to setup a default roblox_sync_config_generator script? No
```
The command will create a `pesde.toml` file in the current folder. Go ahead
and open this file in your text editor of choice.
## Adding a main script
Under the `[target]` section, we're going to add a `bin` field to specify
the path to the main script of our package.
```diff lang="toml" title="pesde.toml"
name = "<username>/hello_pesde"
version = "0.1.0"
license = "MIT"
[target]
environment = "luau"
+ bin = "main.luau"
[indices]
default = "https://github.com/daimond113/pesde-index"
```
Don't forget to save the file after making the changes.
Now, lets create a `main.luau` file in the project folder and add the following
code to it.
```luau title="main.luau"
print("Hello, pesde!")
```
## Running the script
Then, we can run the following command to run the script.
```sh
pesde run
```
You should see `Hello, pesde!` printed to the terminal.
## Install a dependency
Let's use the `pesde/hello` package instead of printing ourselves.
Run the following command to add the package to `pesde.toml`.
```sh
pesde add pesde/hello
```
You should see that `pesde.toml` has been updated with the new dependency.
```diff lang="toml" title="pesde.toml"
name = "lukadev_0/hello_pesde"
version = "0.1.0"
license = "MIT"
[target]
environment = "luau"
bin = "main.luau"
[indices]
default = "https://github.com/daimond113/pesde-index"
+ [dependencies]
+ hello = { name = "pesde/hello", version = "^1.0.0" }
```
Run the following command to install the new dependency.
```sh
pesde install
```
You should see that pesde has created a `luau_packages` folder containing the
newly installed package. It has alsoo created a `pesde.lock` file, this file
contains the exact versions of the dependencies that were installed so that
they can be installed again in the future.
<FileTree>
- luau_packages/
- hello.luau
- ...
- main.luau
- pesde.lock
- pesde.toml
</FileTree>
Let's update the `main.luau` file to use the `pesde/hello` package.
```luau title="main.luau"
local hello = require("./luau_packages/hello")
hello()
```
If we run the script again, we should see something printed to the terminal.
```sh
pesde run
# Hello, pesde! (pesde/hello@1.0.0, luau)
```

191
docs/src/content/docs/reference/cli.mdx Normal file
View file

@ -0,0 +1,191 @@
---
title: pesde CLI
description: Reference for the pesde CLI.
---
import { LinkCard } from '@astrojs/starlight/components'
The pesde CLI is the primary way to interact with pesde projects. It provides
commands for installing dependencies, running scripts, and more.
## `pesde auth`
Authentication-related commands.
### `pesde auth login`
Logs in, stores an authentication token.
- `-i, --index`: The index to authenticate with. Defaults to the default index.
- `-t, --token`: The token to use for authentication.
If no token is provided, you will be prompted to authenticate with GitHub. A
code will be provided that you can paste into the GitHub authentication prompt.
### `pesde auth logout`
Logs out, removes the stored authentication token.
### `pesde auth whoami`
Prints the username of the currently authenticated user.
### `pesde auth set-token-override`
```sh
pesde auth set-token-override <REPOSITORY> [TOKEN]
```
Sets a token override for a specific repository.
## `pesde config`
Configuration-related commands.
### `pesde config default-index`
```sh
pesde config default-index [INDEX]
```
Configures the default index. If no index is provided, the current default index
is printed.
- `-r, --reset`: Resets the default index.
The default index is [`pesde-index`](https://github.com/daimond113/pesde-index).
### `pesde config scripts-repo`
```sh
pesde config scripts-repo [REPO]
```
Configures the scripts repository. If no repository is provided, the current
scripts repository is printed.
- `-r, --reset`: Resets the scripts repository.
The default scripts repository is [`pesde-scripts`](https://github.com/daimond113/pesde-scripts).
## `pesde init`
Initializes a new pesde project in the current directory.
## `pesde run`
Runs a script from the current project using Lune.
```sh
pesde run [SCRIPT] [ -- <ARGS>...]
```
If no script is provided, it will run the script specified by `target.bin`
in `pesde.toml`.
If a path is provided, it will run the script at that path.
If a script defined in `[scripts]` is provided, it will run that script.
If a package name is provided, it will run the script specified by `target.bin`
in that package.
Arguments can be passed to the script by using `--` followed by the arguments.
```sh
pesde run foo -- --arg1 --arg2
```
## `pesde install`
Installs dependencies for the current project.
- `-t, --threads`: The number of threads to use for downloading dependencies.
- `--locked`: Whether to error if the lockfile is out of date.
- `--prod`: Whether to skip installing dev dependencies.
## `pesde publish`
Publishes the current project to the pesde registry.
- `-d, --dry-run`: Whether to perform a dry run. This will output a
tarball containing the package that would be published, but will not actually
publish it.
- `-y, --yes`: Whether to skip the confirmation prompt.
## `pesde self-install`
Performs the pesde installation process. This should be the first command run
after downloading the pesde binary.
## `pesde self-upgrade`
Upgrades the pesde binary to the latest version.
## `pesde patch`
```sh
pesde patch <PACKAGE>
```
Prepares a patching environment for a package. This will copy the source code of
the package to a temporary directory.
The package specified must be in the format `<name>@<version> <target>`.
<LinkCard
title="Overrides"
description="Learn more about overriding and patching packages."
href="/guides/overrides/"
/>
## `pesde patch-commit`
```sh
pesde patch-commit <PATH>
```
Applies the changes made in the patching environment created by `pesde patch`.
## `pesde add`
```sh
pesde add <PACKAGE>
```
Adds a package to the dependencies of the current project.
- `-i, --index <INDEX>`: The index in which to search for the package.
- `-t, --target <TARGET>`: The target environment for the package.
- `-a, --alias <ALIAS>`: The alias to use for the package, defaults to the
package name.
- `-p, --peer`: Adds the package as a peer dependency.
- `-d, --dev`: Adds the package as a dev dependency.
The following formats are supported:
```sh
pesde add pesde/hello
pesde add gh#acme/package#main
pesde add https://git.acme.local/package.git#aeff6
```
## `pesde update`
Updates the dependencies of the current project.
- `-t, --threads`: The number of threads to use for downloading dependencies.
## `pesde x`
Runs a one-off binary package.
```sh
pesde x <PACKAGE>
```
This is useful for running a binary package without installing it or outside of
a pesde project.
```sh
pesde x pesde/hello
```

6
docs/src/content/docs/reference/configuration.md
View file

@ -1,6 +0,0 @@
---
title: Configuration Reference
description: Reference for `pesde.toml`
---
tomlies

405
docs/src/content/docs/reference/manifest.mdx Normal file
View file

@ -0,0 +1,405 @@
---
title: pesde.toml
description: Reference for `pesde.toml`
---
import { LinkCard } from "@astrojs/starlight/components"
`pesde.toml` is the manifest file for a pesde package. It contains metadata about
the package and its dependencies.
## Top-level fields
```toml
name = "acme/package"
version = "1.2.3"
description = "A package that does foo and bar"
license = "MIT"
authors = ["John Doe <john.doe@acme.local> (https://acme.local)"]
repository = "https://github.com/acme/package"
```
### `name`
The name of the package. This is used to identify the package in the registry.
The name consists of a scope and a package name, separated by a slash (`/`). It
may only contain lowercase letters, numbers, and underscores.
The first one to publish to a given scope gets to own it. If you want multiple
people to be able to publish to the same scope, you can send a pull request to
the [pesde-index GitHub repository](https://github.com/daimond113/pesde-index)
and add the GitHub user ID of the other person to the `owners` field of the
`scope.toml` file of the given scope. For more information, see
[policies](/registry/policies#package-ownership).
### `version`
The version of the package. This must be a valid [SemVer](https://semver.org/)
version, such as `1.2.3`.
### `description`
A short description of the package. This is displayed on the package page in the
registry.
### `license`
The license of the package. It is recommended to use a
[SPDX license identifier](https://spdx.org/licenses/), such as `MIT` or
`Apache-2.0`.
### `authors`
A list of authors of the package. Each author is a string containing the name of
the author, optionally followed by an email address in angle brackets, and a
website URL in parentheses. For example:
```toml
authors = ["John Doe <john.doe@acme.local> (https://acme.local)"]
```
### `repository`
The URL of the repository where the package is hosted. This is displayed on the
package page in the registry.
### `private`
A boolean indicating whether the package is private. If set to `true`, the
package cannot be published to the registry.
### `includes`
List of top-level files and directories to include in the package when
publishing. Files not listed here will not be published.
```toml
includes = [
"pesde.toml",
"README.md",
"LICENSE",
"init.luau",
"docs",
]
```
### `pesde_version`
The version of pesde to use within this project. The `pesde` CLI will look at
this field and run the correct version of pesde for this project.
### `workspace_members`
A list of globs containing the members of this workspace.
<LinkCard
title="Workspaces"
description="Learn more about workspaces in pesde."
href="/guides/workspaces/"
/>
## `[target]`
The `[target]` section contains information about the target platform for the
package.
```toml
[target]
environment = "luau"
lib = "init.luau"
```
### `environment`
The target environment for the package. This can be one of the following:
- `luau`: Standalone Luau code that can be run using the `luau` CLI.
- `lune`: Luau code that requires the Lune runtime.
- `roblox`: Luau code that must be run in Roblox.
- `roblox_server`: Same as `roblox`, but only for server-side code.
### `lib`
**Allowed in:** `luau`, `lune`, `roblox`, `roblox_server`
The entry point of the library exported by the package. This file is what will
be required when the package is loaded using `require`.
### `bin`
**Allowed in:** `luau`, `lune`
The entry point of the binary exported by the package. This file is what will be
run when the package is executed as a binary.
<LinkCard
title="Using Binary Packages"
description="Learn more about using binary packages in pesde."
href="/guides/binary-packages/"
/>
### `build_files`
**Allowed in:** `roblox`, `roblox_server`
A list of files that should be synced to Roblox when the package is installed.
```toml
build_files = [
"init.luau",
"foo.luau",
]
```
These files are passed to [`roblox_sync_config_generator`](#roblox_sync_config_generator)
when the package is installed in order to generate the necessary configuration.
## `[scripts]`
The `[scripts]` section contains scripts that can be run using the `pesde run`
command. These scripts are run using [Lune](https://lune-org.github.io/docs).
```toml
[scripts]
build = "sripts/build.luau"
test = "scripts/test.luau"
```
There are also a few special scripts that are run in certain cases by pesde.
### `roblox_sync_config_generator`
This is responsible for generating adequate configuration files for Roblox
sync tools.
`process.args` will contain the directory containing the package, and the list
of files specified within the [`target.build_files`](#build_files) of the
package.
You can find template scripts inside the
[`pesde-scripts` repository](https://github.com/daimond113/pesde-scripts)
for various sync tools.
<LinkCard
title="Roblox"
description="Learn more about using pesde in Roblox projects."
href="/guides/roblox/"
/>
<LinkCard
title="Example script for Rojo"
description="An example script for generating configuration for Rojo."
href="https://github.com/daimond113/pesde-scripts/blob/master/lune/rojo/roblox_sync_config_generator.luau"
/>
### `sourcemap_generator`
This is responsible for generating source maps for packages that are installed.
This is required to get proper types support when using
[Wally dependencies](/guides/dependencies/#wally-dependencies).
The script will receive the path to the package directory as the first argument
through `process.args`.
<LinkCard
title="Example script for Rojo"
description="An example script for generating configuration for Rojo."
href="https://github.com/daimond113/pesde-scripts/blob/master/lune/rojo/sourcemap_generator.luau"
/>
## `[indices]`
The `[indices]` section contains a list of pesde indices where packages can be
installed from.
```toml
[indices]
default = "https://github.com/daimond113/pesde-index"
acme = "https://github.com/acme/pesde-index"
```
These can then be referenced in the [`dependencies`](#dependencies) of the
package. The `default` index is used if no index is specified.
```toml
[dependencies]
foo = { name = "acme/foo", version = "1.2.3", index = "acme" }
```
## `[wally_indices]`
The `[wally_indices]` section contains a list of Wally indices where packages
can be installed from. This is used for
[Wally dependencies](/guides/dependencies/#wally-dependencies).
```toml
[wally_indices]
default = "https://github.com/UpliftGames/wally-index"
acme = "https://github.com/acme/wally-index"
```
These can then be referenced in the [`dependencies`](#dependencies) of the
package. The `default` index is used if no index is specified.
```toml
[dependencies]
foo = { wally = "acme/foo", version = "1.2.3", index = "acme" }
```
## `[overrides]`
The `[overrides]` section contains a list of overrides for dependencies. This
allows you to replace certain dependencies with different versions or even
different packages.
```toml
[overrides]
"bar>baz" = { name = "acme/baz", version = "1.0.0" }
"foo>bar,baz>bar" = { name = "acme/bar", version = "2.0.0" }
```
The above example will replace the `baz` dependency of the `bar` package with
version `1.0.0`, and the `bar` and `baz` dependencies of the `foo` package with
version `2.0.0`.
Each key in the overrides table is a comma-separated list of package paths. The
path is a list of package names separated by `>`. For example, `foo>bar>baz`
refers to the `baz` dependency of the `bar` package, which is a dependency of
the `foo` package.
<LinkCard
title="Overrides"
description="Learn more about overriding and patching packages."
href="/guides/overrides/"
/>
## `[patches]`
The `[patches]` section contains a list of patches for dependencies. This allows
you to modify the source code of dependencies.
```toml
[patches]
"acme/foo" = { "1.0.0 luau" = "patches/acme+foo-1.0.0+luau.patch" }
```
The above example will patch version `1.0.0` with the `luau` target of the
`acme/foo` package using the `patches/acme+foo-1.0.0+luau.patch` file.
Each key in the patches table is the package name, and the value is a table
where the keys are the version and target, and the value is the path to the
patch.
The patches can be generated using the `pesde patch` command.
<LinkCard
title="Overrides"
description="Learn more about overriding and patching packages."
href="/guides/overrides/"
/>
## `[place]`
This is used in Roblox projects to specify where packages are located in the
Roblox datamodel.
```toml
[place]
shared = "game.ReplicatedStorage.Packages"
server = "game.ServerScriptService.Packages"
```
## `[dependencies]`
The `[dependencies]` section contains a list of dependencies for the package.
```toml
[dependencies]
foo = { name = "acme/foo", version = "1.2.3" }
bar = { wally = "acme/bar", version = "2.3.4" }
baz = { git = "acme/baz", rev = "main" }
```
Each key in the dependencies table is the name of the dependency, and the value
is a dependency specifier.
There are several types of dependency specifiers.
### pesde
```toml
[dependencies]
foo = { name = "acme/foo", version = "1.2.3", index = "acme", target = "lune" }
```
**pesde dependencies** contain the following fields:
- `name`: The name of the package.
- `version`: The version of the package.
- `index`: The [pesde index](#indices) to install the package from. If not
specified, the `default` index is used.
- `target`: The target platform for the package. If not specified, the target
platform of the current package is used.
### Wally
```toml
[dependencies]
foo = { wally = "acme/foo", version = "1.2.3", index = "acme" }
```
**Wally dependencies** contain the following fields:
- `wally`: The name of the package.
- `version`: The version of the package.
- `index`: The [Wally index](#wally_indices) to install the package from. If not
specified, the `default` index is used.
### Git
```toml
[dependencies]
foo = { git = "acme/packages", rev = "main", path = "foo" }
```
**Git dependencies** contain the following fields:
- `git`: The URL of the Git repository.
This can either be `<owner>/<name>` for a GitHub repository, or a full URL.
- `rev`: The Git revision to install. This can be a branch, tag, or commit hash.
- `path`: The path within the repository to install. If not specified, the root
of the repository is used.
## `[peer_dependencies]`
The `[peer_dependencies]` section contains a list of peer dependencies for the
package. These are dependencies that are required by the package, but are not
installed automatically. Instead, they must be installed by the user of the
package.
```toml
[peer_dependencies]
foo = { name = "acme/foo", version = "1.2.3" }
```
## `[dev_dependencies]`
The `[dev_dependencies]` section contains a list of development dependencies for
the package. These are dependencies that are only required during development,
such as testing libraries or build tools. They are not installed when the
package is used by another package.
```toml
[dev_dependencies]
foo = { name = "acme/foo", version = "1.2.3" }
```
<br/>
<LinkCard
title="Specifying Dependencies"
description="Learn more about specifying dependencies in pesde."
href="/guides/dependencies/"
/>

66
docs/src/content/docs/registry/policies.md Normal file
View file

@ -0,0 +1,66 @@
---
title: Policies
description: Policies for the pesde registry
---
If anything is unclear, please [contact us](#contact-us). and we will be happy
to help.
## Contact Us
You can contact us at [pesde@daimond113.com](malto:pesde@daimond113.com).
## Permitted content
The pesde registry is a place for Luau packages. Examples of allowed content:
- Libraries
- Frameworks
Examples of disallowed content:
- Malicious code
- Illegal content
pesde is not responsible for the content of packages. If you believe a package
is breaking these requirements, please [contact us](#contact-us).
## Package removal
pesde does not support removing packages from the registry without a reason such
as security or complying with the law in order. In case a secret has been
published to the registry, it must be invalided. If you believe a package should
be removed, please [contact us](#contact-us). We will review your request and
take action if necessary.
If we find that a package is breaking the permitted content policy, we will
remove it from the registry without notice.
pesde reserves the right to remove any package from the registry at any time for
any or no reason, without notice.
## Package ownership
Packages are owned by scopes. The first person to publish to a scope owns it. If
you want to work as a team, the owner of the scope must send a pull request to
the index repository adding the members' user IDs to the scope's `scope.toml`
file.
## Scope squatting
Scope squatting is the act of creating a scope with the intent of preventing
others from using it. Scope squatting is not allowed. If you believe a scope is
being squatted, please [contact us](#contact-us). We will review your request
and take action if necessary.
## API Usage
The pesde registry has an API for searching packages, downloading, and
publishing them. Only non-malicious use is permitted. Malicious uses include:
- **Service Degradation**: this includes sending the registry an excessive
amount of requests
- **Exploitation**: this includes trying to break security of the registry in
order to gain unauthorized access to resources
- **Harmful content**: this includes publishing harmful (non-law compliant,
purposefully insecure) content

6
docs/tailwind.config.ts
View file

@ -1,5 +1,5 @@
import type { Config } from "tailwindcss"
import starlightPlugin from "@astrojs/starlight-tailwind"
import type { Config } from "tailwindcss"
import defaultTheme from "tailwindcss/defaultTheme"
export default {
@ -20,8 +20,8 @@ export default {
gray: {
100: "rgb(245 230 210)",
200: "rgb(228 212 192)",
300: "rgb(180 160 140)",
400: "rgb(130 90 40)",
300: "rgb(198 167 140)",
400: "rgb(142 128 112)",
500: "rgb(84 70 50)",
600: "rgb(65 50 41)",
700: "rgb(50 42 35)",