mirror of
https://github.com/pesde-pkg/pesde.git
synced 2025-03-13 15:34:28 +00:00
259 lines
8.3 KiB
Svelte
259 lines
8.3 KiB
Svelte
<script lang="ts">
|
|
import Codeblock from '$lib/Codeblock.svelte';
|
|
import Note from './Note.svelte';
|
|
</script>
|
|
|
|
<svelte:head>
|
|
<title>pesde documentation</title>
|
|
<meta content="pesde documentation" property="og:title" />
|
|
<meta content="Documentation about using pesde" name="description" />
|
|
<meta content="Documentation about using pesde" property="og:description" />
|
|
</svelte:head>
|
|
|
|
<div class="max-w-prose">
|
|
<h1>Using pesde</h1>
|
|
|
|
<section>
|
|
<h2>Initializing a package</h2>
|
|
<p>
|
|
Even if you're not making a package, but something else such as a game, you will still need to
|
|
initialize package.
|
|
</p>
|
|
<Codeblock code="pesde init" />
|
|
<p>This will prompt you questions, after which it will create a pesde.yaml file.</p>
|
|
<Note>
|
|
If you are using pesde with the `wally` feature enabled (true on releases from the GitHub
|
|
repository) then you can use <Codeblock code="pesde convert" /> to convert your wally.toml file
|
|
to pesde.yaml. This will leave you with an empty default index, so you will need to add a URL (such
|
|
as the default `<a href="https://github.com/daimond113/pesde-index"
|
|
>https://github.com/daimond113/pesde-index</a
|
|
>`) yourself.
|
|
</Note>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Adding dependencies</h2>
|
|
<p>
|
|
You can use the `add` command to add dependencies to your project. With the `wally` feature
|
|
enabled, you can add Wally dependencies.
|
|
</p>
|
|
<p>
|
|
If you are making a package, you can use the `--peer` argument to add a package as a peer
|
|
dependency. Peer dependencies are not installed when the package is installed, but are
|
|
required to be installed by the user of the package. This is useful for things like framework
|
|
plugins.
|
|
</p>
|
|
<p>
|
|
If you want to declare the dependency as server or development only, you can use the `--realm
|
|
server` or `--realm development` arguments respectively. The `shared` realm is the default.
|
|
</p>
|
|
<Codeblock
|
|
code="pesde add --realm server SCOPE/NAME@VERSION
|
|
pesde add --realm development wally#SCOPE/NAME@VERSION # for Wally packages"
|
|
/>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Overriding dependencies</h2>
|
|
<p>
|
|
Dependency overrides allow you to use a different version of a dependency than the one
|
|
specified in the package. This is useful for sharing 1 version of a dependency.
|
|
</p>
|
|
<p>
|
|
Dependency overrides use the keys in the format of desired names separated with `>`, and
|
|
optionally other paths separated with `,`. The value is a dependency specifier.
|
|
</p>
|
|
<Note class="mb-4">
|
|
Dependency overrides do not have a command. You will need to edit the pesde.yaml file
|
|
yourself.
|
|
</Note>
|
|
<Codeblock
|
|
lang="yaml"
|
|
code="overrides:
|
|
DESIRED_NAME>DEPENDENCY_DESIRED_NAME,DESIRED_NAME_2>DEPENDENCY_DESIRED_NAME_2:
|
|
name: SCOPE/NAME
|
|
version: VERSION"
|
|
/>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Removing dependencies</h2>
|
|
<p>You can use the `remove` command to remove dependencies from your project.</p>
|
|
<Codeblock
|
|
code="pesde remove SCOPE/NAME@VERSION
|
|
pesde remove wally#SCOPE/NAME@VERSION"
|
|
/>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Outdated dependencies</h2>
|
|
<p>
|
|
You can list outdated dependencies with the `outdated` command. This will list all
|
|
dependencies that have a newer version available.
|
|
</p>
|
|
<Note class="mb-4">
|
|
This command only supports pesde registries, so neither Git nor Wally dependencies will be
|
|
listed.
|
|
</Note>
|
|
<Codeblock code="pesde outdated" />
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Installing a project</h2>
|
|
<p>The `install` command will install all dependencies of a project.</p>
|
|
<p>
|
|
You can use the `--locked` argument to skip resolving and read the dependencies from the
|
|
lockfile. If any changes were made from the time the lockfile was generated this will error.
|
|
</p>
|
|
<Codeblock code="pesde install" />
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Running a bin dependency</h2>
|
|
<p>
|
|
Dependencies may export a bin script. You can run this script with the `run` command. The
|
|
script will be executed with Lune. You can use the `--` argument to pass arguments to the
|
|
script.
|
|
</p>
|
|
<Note class="mb-4">
|
|
This does <b>not</b> support Wally dependencies.
|
|
</Note>
|
|
<Codeblock code="pesde run SCOPE/NAME -- -arg" />
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Patching dependencies</h2>
|
|
<p>
|
|
You can use the `patch` command to patch a dependency. This will output a directory in which
|
|
you can edit the dependency. After you are done, run the `patch-commit` command with the
|
|
directory as an argument to commit the changes.
|
|
</p>
|
|
<Codeblock
|
|
code="pesde patch SCOPE/NAME@VERSION
|
|
pesde patch-commit DIRECTORY"
|
|
/>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Publishing a package</h2>
|
|
<p>
|
|
You can publish a package with the `publish` command. This will upload the package to the
|
|
registry. This will publish to the `default` index.
|
|
</p>
|
|
<Note class="mb-4"
|
|
>The official pesde registry does not support publishing packages with Wally or Git
|
|
dependencies. Dependency overrides and patches of your package as a dependency will be
|
|
ignored.</Note
|
|
>
|
|
<Codeblock code="pesde publish" />
|
|
<p>
|
|
Please look at the <a href="#cheatsheet">manifest format cheat sheet</a> for more information about
|
|
the pesde.yaml file before publishing.
|
|
</p>
|
|
</section>
|
|
|
|
<section>
|
|
<h2>Searching for packages</h2>
|
|
<p>
|
|
You can search for packages with the `search` command. This will list all packages that match
|
|
the query. It will search by name and description.
|
|
</p>
|
|
<Codeblock code="pesde search QUERY" />
|
|
</section>
|
|
|
|
<section>
|
|
<h2 id="cheatsheet">Manifest format cheat sheet</h2>
|
|
<p>
|
|
Here is a cheat sheet for the manifest format. This is the format of the pesde.yaml file. The
|
|
`name` and `version` fields are required. All other fields are optional.
|
|
</p>
|
|
<p>A description of each type:</p>
|
|
<ul>
|
|
<li>PACKAGE_NAME: either a STANDARD_PACKAGE_NAME or WALLY_PACKAGE_NAME</li>
|
|
<li>STANDARD_PACKAGE_NAME: refers to a package name used by pesde</li>
|
|
<li>
|
|
WALLY_PACKAGE_NAME: refers to a package name used by Wally. This will usually be prefixed
|
|
with `wally#`, although not required when this rather than `PACKAGE_NAME` is the type
|
|
</li>
|
|
<li>VERSION: a semver version specifier</li>
|
|
<li>VERSION_REQ: a semver version requirement</li>
|
|
<li>REALM: one of `shared`, `server`, or `development`</li>
|
|
<li>COMMAND: a command to run</li>
|
|
<li>
|
|
DEPENDENCY_SPECIFIER: one of REGISTRY_DEPENDENCY_SPECIFIER, GIT_DEPENDENCY_SPECIFIER,
|
|
WALLY_DEPENDENCY_SPECIFIER
|
|
</li>
|
|
<li>
|
|
REGISTRY_DEPENDENCY_SPECIFIER: an object with the following structure:
|
|
<Codeblock
|
|
lang="yaml"
|
|
code="name: STANDARD_PACKAGE_NAME
|
|
version: VERSION_REQ
|
|
# OPTIONAL (name in the `indices` field) - defaults to `default`
|
|
index: STRING"
|
|
/>
|
|
</li>
|
|
<li>
|
|
GIT_DEPENDENCY_SPECIFIER: an object with the following structure:
|
|
<Codeblock
|
|
lang="yaml"
|
|
code="repo: URL
|
|
rev: STRING"
|
|
/>
|
|
</li>
|
|
<li>
|
|
WALLY_DEPENDENCY_SPECIFIER: an object with the following structure:
|
|
<Codeblock
|
|
lang="yaml"
|
|
code="wally: WALLY_PACKAGE_NAME
|
|
version: VERSION_REQ
|
|
index_url: URL"
|
|
/>
|
|
</li>
|
|
</ul>
|
|
<Codeblock
|
|
lang="yaml"
|
|
code="name: PACKAGE_NAME
|
|
version: VERSION
|
|
description: STRING
|
|
license: STRING
|
|
authors: STRING[]
|
|
repository: URL
|
|
exports:
|
|
lib: PATH
|
|
bin: PATH
|
|
path_style: !roblox
|
|
place: {
|
|
REALM: STRING
|
|
}
|
|
private: BOOL
|
|
realm: REALM
|
|
indices:
|
|
STRING: URL
|
|
# WALLY FEATURE ONLY
|
|
sourcemap_generator: COMMAND
|
|
overrides:
|
|
OVERRIDE_KEY: DEPENDENCY_SPECIFIER
|
|
|
|
dependencies: DEPENDENCY_SPECIFIER[]
|
|
peer_dependencies: DEPENDENCY_SPECIFIER[]"
|
|
/>
|
|
<p>The exports field is used to specify the paths of the package's exports:</p>
|
|
<ul>
|
|
<li>
|
|
The `lib` field is a path to the file which will become the ModuleScript of the package.
|
|
This is only used for reading the types of the package.
|
|
</li>
|
|
<li>The `bin` field is a path to the file which will be ran with the `run` command.</li>
|
|
</ul>
|
|
<p>
|
|
If the realm field is not specified, it will default to `shared`. If it is another value, and
|
|
the package is to be installed in a different realm, pesde will error.
|
|
</p>
|
|
<p>
|
|
The sourcemap generator command is only used for Wally and Git packages. It will be ran in a
|
|
package's directory, and must output a sourcemap file. This is used to generate a sourcemap
|
|
for the package so that types may be found and re-exported.
|
|
</p>
|
|
</section>
|
|
</div>
|