From 4a3619c26e3c0a9938c68d99b85f148e435290bb Mon Sep 17 00:00:00 2001 From: daimond113 <72147841+daimond113@users.noreply.github.com> Date: Wed, 11 Dec 2024 21:37:59 +0100 Subject: [PATCH] docs: document scripts packages --- .../content/docs/guides/scripts-packages.mdx | 53 +++++++++++++++++++ docs/src/content/docs/reference/manifest.mdx | 12 +++++ registry/src/package.rs | 6 +++ website/src/lib/registry-api.ts | 1 + .../[[version]]/[[target]]/+layout.svelte | 34 ++++++++---- 5 files changed, 95 insertions(+), 11 deletions(-) create mode 100644 docs/src/content/docs/guides/scripts-packages.mdx diff --git a/docs/src/content/docs/guides/scripts-packages.mdx b/docs/src/content/docs/guides/scripts-packages.mdx new file mode 100644 index 0000000..7ba6b82 --- /dev/null +++ b/docs/src/content/docs/guides/scripts-packages.mdx @@ -0,0 +1,53 @@ +--- +title: Using Scripts Packages +description: Learn how to use scripts packages. +--- + +A **scripts package** is a package that contains scripts. The scripts provided +by the package are linked in `.pesde/{alias}/{script_name}.luau` of the project +that uses the package. + +## Using a scripts package + +Scripts 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 scripts package to the `dependencies` section of the file. + +```sh +pesde add pesde/scripts_rojo +pesde install +``` + +This will add the scripts package to your project, and installing will put the +scripts at `.pesde/scripts_rojo/{script_name}.luau`. You can then add the scripts +to your manifest, for example: + +```toml title="pesde.toml" +[scripts] +roblox_sync_config_generator = ".pesde/scripts_rojo/roblox_sync_config_generator.luau" +``` + +## Making a scripts package + +To make a scripts package you must use a target compatible with scripts exports. +These currently are `lune` and `luau`. + +Here is an example of a scripts package: + +```toml title="pesde.toml" +name = "pesde/scripts_rojo" +version = "1.0.0" +license = "MIT" + +[target] +environment = "lune" + +[target.scripts] +roblox_sync_config_generator = "roblox_sync_config_generator.luau" +``` + +The `scripts` table in the target is a map of script names to the path of the +script in the package. The scripts will be linked in the project that uses the +package at `.pesde/{alias}/{script_name}.luau`. diff --git a/docs/src/content/docs/reference/manifest.mdx b/docs/src/content/docs/reference/manifest.mdx index f52351a..528f4e1 100644 --- a/docs/src/content/docs/reference/manifest.mdx +++ b/docs/src/content/docs/reference/manifest.mdx @@ -155,6 +155,18 @@ build_files = [ 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` + +**Allowed in:** `luau`, `lune` + +A list of scripts that will be linked to the project's `.pesde` directory, and +copied over to the [scripts](#scripts-1) section when initialising a project with +this package. + +```toml +scripts = { roblox_sync_config_generator = "scripts/roblox_sync_config_generator.luau" } +``` + ## `[scripts]` The `[scripts]` section contains scripts that can be run using the `pesde run` diff --git a/registry/src/package.rs b/registry/src/package.rs index 93ad5e8..5ef6cce 100644 --- a/registry/src/package.rs +++ b/registry/src/package.rs @@ -8,6 +8,8 @@ pub struct TargetInfo { kind: TargetKind, lib: bool, bin: bool, + #[serde(skip_serializing_if = "BTreeSet::is_empty")] + scripts: BTreeSet, } impl From for TargetInfo { @@ -22,6 +24,10 @@ impl From<&Target> for TargetInfo { kind: target.kind(), lib: target.lib_path().is_some(), bin: target.bin_path().is_some(), + scripts: target + .scripts() + .map(|scripts| scripts.keys().cloned().collect()) + .unwrap_or_default(), } } } diff --git a/website/src/lib/registry-api.ts b/website/src/lib/registry-api.ts index 99900ae..743870d 100644 --- a/website/src/lib/registry-api.ts +++ b/website/src/lib/registry-api.ts @@ -26,6 +26,7 @@ export type TargetInfo = { kind: TargetKind lib: boolean bin: boolean + scripts?: string[] } export type TargetKind = "roblox" | "roblox_server" | "lune" | "luau" diff --git a/website/src/routes/(app)/packages/[scope]/[name]/[[version]]/[[target]]/+layout.svelte b/website/src/routes/(app)/packages/[scope]/[name]/[[version]]/[[target]]/+layout.svelte index 0744971..4ebfaea 100644 --- a/website/src/routes/(app)/packages/[scope]/[name]/[[version]]/[[target]]/+layout.svelte +++ b/website/src/routes/(app)/packages/[scope]/[name]/[[version]]/[[target]]/+layout.svelte @@ -2,7 +2,7 @@ import { page } from "$app/stores" import GitHub from "$lib/components/GitHub.svelte" import type { TargetInfo } from "$lib/registry-api" - import { BinaryIcon, Globe, Icon, LibraryIcon, Mail } from "lucide-svelte" + import { BinaryIcon, Globe, Icon, LibraryIcon, Mail, ScrollIcon } from "lucide-svelte" import type { ComponentType } from "svelte" import TargetSelector from "../../TargetSelector.svelte" import Command from "./Command.svelte" @@ -36,11 +36,13 @@ const exportNames: Partial> = { lib: "Library", bin: "Binary", + scripts: "Scripts", } const exportIcons: Partial>> = { lib: LibraryIcon, bin: BinaryIcon, + scripts: ScrollIcon, } const exportEntries = $derived( @@ -92,20 +94,30 @@
    {#each exportEntries as [exportKey, exportName]} {@const Icon = exportIcons[exportKey as keyof TargetInfo]} -
  • -
  • +
    +
    + {#if exportKey === "bin"} +

    + This package provides a binary that can be executed after installation, or globally + via: +

    + + {:else if exportKey === "scripts"} +
    + {#each currentTarget?.scripts ?? [] as script} +
    + {script} +
    + {/each} +
    + {/if}
    • {/each}
- {#if currentTarget?.bin} -

- This package provides a binary that can be executed after installation, or globally via: -

- - {/if} - {#if data.pkg.authors && data.pkg.authors.length > 0}

Authors