Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

new-unit

/new-unit

Generuje kompletny plik jednostki Starlark .star dla Yoe na podstawie adresu URL źródła lub opisu.

Repozytorium
yoe ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
20.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
8
Przestarzałość

Brak sygnałów. Repozytorium zmienione 20.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Generuje kompletny plik jednostki Starlark .star dla Yoe na podstawie adresu URL źródła lub opisu.

Wyzwalacze z opisu

create a unitadd a unitnew unitpackage something
Oryginalny opis (EN)

This skill should be used when the user asks to "create a unit", "add a unit", "new unit", "package something", "/new-unit", or provides a URL or project name to be packaged for Yoe. Generates a complete Starlark .star unit file from a source URL or description.

Jak działa

  1. Before You Build From Source: Check the Alpine Feed
  2. Workflow
  3. Unit Conventions
  4. Dependency Policy
  5. What NOT to Do
Sekcje z nagłówków SKILL.md, w oryginale · 266 linii, 1 522 słów
Podgląd SKILL.md
---
name: new-unit
description: >
  This skill should be used when the user asks to "create a unit", "add a unit",
  "new unit", "package something", "/new-unit", or provides a URL or project
  name to be packaged for Yoe. Generates a complete Starlark .star unit file
  from a source URL or description.
---

# Create a New Unit

Generate a complete Starlark `.star` unit from an upstream source URL or a
natural language description. The output is a ready-to-build unit that follows
existing conventions in the project's modules.

## Before You Build From Source: Check the Alpine Feed

If the thing you need is a tool or library Alpine already ships — a cross
toolchain, a niche build tool, a runtime you don't want to maintain — **do not
write a from-source unit.** `module-alpine` exposes all of Alpine `main` and
`community` as lazily-materialized feeds (`alpine.main`, `alpine.community`).
Pull the package by name and route it with `prefer_modules` in PROJECT.star; no
per-package file is generated. See the `pulling-alpine-packages` skill for the
workflow. Write a from-source unit only when Alpine doesn't ship the package,
ships the wrong version, or the build _is_ the product (kernel, bootloader,
busybox, base-files, project libraries you will patch via `yoe dev`).

## Workflow

### Step 1: Determine the Source

If the user provides a URL (GitHub repo, tarball, etc.), use it directly. If the
user provides a description ("I need an MQTT broker"), research appropriate
upstream projects and suggest one, confirming with the user before proceeding.

### Step 2: Research Existing Packaging

Before writing the unit from scratch, check how other distributions package the
same software. These are valuable references for configure flags, dependencies,
patches, and known pitfalls:

- **Alpine Linux (APKBUILD)** — search
  `https://gitlab.alpinelinux.org/alpine/aports` for the package. Alpine is
  closest to Yoe's packaging model (apk, musl/glibc, minimal). Pay attention to
  `makedepends`, `depends`, and `configure` flags.
- **Yocto/OpenEmbedded (bitbake units)** — search
  `https://layers.openembedded.org` or the OE-Core module. Yocto units often
  have well-tested configure flags and patch sets for embedded use.
- **Buildroot** — search
  `https://github.com/buildroot/buildroot/tree/master/package` for the package.
  Buildroot units are simple and often reveal minimal configure flags needed for
  embedded targets.

Extract useful information: required dependencies, recommended configure flags,
known patches, and license details. Do not blindly copy — adapt to Yoe's
conventions and verify the information is current.

### Step 3: Inspect the Source

Fetch and inspect the upstream source to determine:

1. **Build system** — look for these files in priority order:
   - `configure.ac` / `Makefile.am` → autotools class (`autotools`)
   - `CMakeLists.txt` → cmake class (`cmake`)
   - `go.mod` → go class (`go_binary`)
   - `package.json` with a Bun lockfile / Bun runtime → bun class (`bun_app`)
   - `package.json` with npm/Node → nodejs class (`nodejs_app`)
   - Python project (`pyproject.toml` / `requirements.txt`) → python class
     (`python_venv`, takes a `pip_packages` list)
   - Upstream ships a prebuilt binary release (no compile) → binary class
     (`binary`, fetches a release artifact by URL + `sha256`)
   - `Makefile` only → custom build steps with `unit()`
   - `meson.build` → custom build steps (no meson class yet)

   The `bun_app`, `nodejs_app`, `python_venv`, and `binary` classes are the "app
   mode" classes — use them for application payloads (services, tools shipped as
   an interpreted app or a prebuilt binary) rather than libraries compiled into
   the system.

2. **Version** — latest stable release tag or version string

3. **Dependencies** — scan `configure.ac`, `CMakeLists.txt`, `go.mod`,
   `pkg-config` requires, or `#include` directives to identify build and runtime
   dependencies. Cross-reference against existing units in the project's modules
   and the findings from Step 2.

4. **License** — check `LICENSE`, `COPYING`, or source headers. Use SPDX
   identifiers (e.g., `MIT`, `Apache-2.0`, `GPL-2.0-or-later`).

### Step 4: Check for Existing Units

Before creating a new unit, search all modules for an existing unit:

```
Glob: modules/**/units/**/<name>.star
```

If one exists, inform the user and suggest `/update-unit` instead.

### Step 5: Generate the Unit

Write a `.star` file following the conventions of existing units in the project.
Use the appropriate class:

**Autotools example:**

```python
load("//classes/autotools.star", "autotools")

autotools(
    name = "example",
    version = "1.2.3",
    source = "https://github.com/example/example.git",
    tag = "v1.2.3",
    license = "MIT",
    description = "Short description of the package",
    deps = ["zlib", "openssl"],
    runtime_deps = ["zlib", "openssl"],
    configure_args = ["--with-ssl"],
)
```

**CMake example:**

```python
load("//classes/cmake.star", "cmake")

cmake(
    name = "example",
    version = "1.2.3",
    source = "https://github.com/example/example.git",
    tag = "v1.2.3",
    license = "MIT",
    description = "Short description of the package",
    deps = ["zlib"],
    runtime_deps = ["zlib"],
    cmake_args = ["BUILD_SHARED_LIBS=ON"],
)
```

**Go example:**

```python
load("//classes/go.star", "go_binary")

go_binary(
    name = "example",
    version = "1.2.3",
    source = "https://github.com/example/example.git",
    tag = "v1.2.3",
    license = "Apache-2.0",
    description = "Short description of the package",
)
```

**Custom build (no class):**

```python
unit(
    name = "example",
    version = "1.2.3",
    source = "https://github.com/example/example.git",
    tag = "v1.2.3",
    license = "MIT",
    description = "Short description of the package",
    deps = ["zlib"],
    runtime_deps = ["zlib"],
    build = [
        "./configure --prefix=$PREFIX",
        "make -j$NPROC",
        "make DESTDIR=$DESTDIR install",
    ],
)
```

### Step 6: Choose the File Location

Place the unit in the appropriate category directory within the project's module
or the module-core module:

| Category    | Directory            | Examples               |
| ----------- | -------------------- | ---------------------- |
| Libraries   | `units/libs/`        | zlib, openssl, ncurses |
| Networking  | `units/net/`         | openssh, curl          |
| Base system | `units/base/`        | busybox, linux         |
| Debug tools | `units/debug/`       | strace, vim            |
| Bootloaders | `units/bootloaders/` | syslinux               |

If no existing category fits, create a new one (e.g., `units/multimedia/`).

### Step 7: Confirm and Write

Present the complete unit to the user for review before writing the file. Show
the file path and contents. Only write after confirmation.

### Step 8: Test Build

After writing the unit, build it to verify:

```bash
yoe build --force <unit-name>
```

If the build fails, use the diagnose workflow to fix it iteratively.

## Unit Conventions

- **Prefer git sources** over tarballs — use `source` with a `.git` URL and
  `tag` for version pinning
- **Exception: GNU packages hosted on savannah.** `git.savannah.gnu.org`
  regularly stalls mid-clone and fails the build with
  `Operation too slow. Less than 1000 bytes/sec transferred the last 60 seconds`.
  For a package that publishes GNU FTP releases, take the tarball
  (`https://ftp.gnu.org/gnu/<pkg>/<pkg>-<version>.tar.gz`) with a `sha256`
  instead. A tarball also picks up a second host from the project's
  `source_mirrors` table, which rewrites `ftp.gnu.org/gnu` to
  `mirrors.kernel.org/gnu`; mirrors apply only to HTTP fetches, so a git source
  has no fallback when its host is unavailable. `readline` and `gawk` are the
  worked examples. Release tarballs ship a generated `configure` whose
  regeneration rules are commented out, so the `autotools` class's
  `autoreconf -fi` step is unnecessary — override the build task to drop it if
  the unit already defines one.
- **Tag format** varies by project — inspect the upstream repo's tags (e.g.,
  `v1.2.3`, `release-1.2.3`, `openssl-3.4.1`)
- **deps vs runtime_deps** — `deps` are build-time only (headers, static libs);
  `runtime_deps` are needed at runtime. Most libraries are both.
- **configure_args** — only add flags that differ from defaults. Do not add
  `--prefix=$PREFIX` (the class handles it).
- **license** — use SPDX identifiers. Check the upstream project carefully.
- **description** — one sentence, lowercase start, no trailing period
- **provides** — almost always omit. `provides` is a `[]string` of virtual
  package names this unit satisfies; it is reserved for **leaf artifacts** that
  get swapped per machine or per project: kernel, base-files, init, bootloader.
  Do **not** set `provides` on a build-time library, a generic tool (less, htop,
  file, etc.), or a daemon that has a busybox alternative — those should ship
  side-by-side and be selected at boot from init scripts. Misusing `provides`
  forks every transitive consumer into a machine-specific apk variant. See
  `docs/naming-and-resolution.md` §"When NOT to use provides".
- **replaces** — `[]string` listing packages whose files this unit may overwrite
  at install time. Set this only when the unit ships a path that is also owned
  by another package and you want apk to accept the shadow rather than fail.
  Example: `util-linux` ships real `dmesg`/`mount`/`umount` etc. at paths
  busybox also claims, so its unit declares `replaces = ["busybox"]`. Without
  the annotation, `apk add` rejects the conflict at image-assembly time.
- **Generic units must not depend on machine-flavored units.** A library or
  tool's `deps` and `runtime_deps` should reference only other libraries and
  tools. Never add `linux`, `base-files`, or any unit that varies by machine to
  a generic unit's deps — it will fork that unit's apk per machine.

## Dependency Policy

**Never install missing dependencies in the Dockerfile.** The container provides
only the minimal bootstrap toolchain (gcc, binutils, make, etc.). Every library
and build tool the unit needs must exist as a unit:

- If a dependency already has a unit, add it to `deps` (and `runtime_deps` if
  it's a shared library needed at runtime).
- If no unit exists for the dependency, **create one first** before writing the
  unit that depends on it. Use this same workflow recursively.
- For non-essential build-time features (doc generation, man pages, GUI
  bindings), prefer disabling them via configure flags over adding deps.

## What NOT to Do

- Do not guess dependencies — inspect the build system files and reference other
  distributions' units to find them.
- Do not hardcode absolute paths in build commands — use `$PREFIX`, `$DESTDIR`,
  `$NPROC` environment variables.
- Do not add a unit to `module-core` unless it's truly a core system component.
  Project-specific units go in the project's own module.
- Do not skip the test build step.
- Do not install missing tools or libraries in the Dockerfile — create units for
  them instead.

Wersje

RepozytoriumWynikLicencja
Ta strona · yoebuild/yoe100Apache-2.0
e-reitbauer/habits100MIT

Migawka bazy z 13.11.2026 · wersja paczki 8670cd0f3c4e (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95starlark-dev
    Tworzy i debuguje pakiety Kurtosis w Starlarku, w tym testy lokalne i diagnostykę przez print().
  • 100audit-unit
    Przegląda unit pod kątem poprawności, kompletności i jakości oraz sprawdza zgodność z dobrymi praktykami i typowymi problemami.
  • 100create-unit-test
    Pisze lub refaktoryzuje testy jednostkowe według kanonicznego wzorca projektu, także ujednolicając istniejące.
  • 100ship-unit
    Otwiera PR dla ukończonej jednostki pracy, sprawdza kryteria akceptacji i prosi o zewnętrzną recenzję.
  • 100bazel
    Konfiguruje i diagnozuje buildy Bazel: pliki BUILD i MODULE.bazel, Starlark, błędy targetów, cache i CI oraz adopcję lub aktualizację Bazela.
  • 100unit-testing
    Pisze i aktualizuje testy jednostkowe dla nowego lub zmienionego kodu, uruchamia je z pokryciem i naprawia błędy.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.