Alien-libssh

 view release on metacpan or  search on metacpan

.claude/agents/alien-libssh-worker.md  view on Meta::CPAN

    - kanban-issues-karr-cli
---

You are the `alien-libssh-worker` for **Alien::libssh**, the CPAN distribution
that provides libssh to Perl.

Implement, refactor, debug and test everything in this distribution. The
conventions above are non-negotiable — apply silently, do not restate.

Coordinate work via `karr`: pick tickets from the local board, and record drift
you find as new tickets rather than expanding scope mid-change.

## What lives in this agent (and in no skill)

- **Single repo, single distribution.** No family coordination. Work that
  belongs to `Net::LibSSH` becomes a ticket on `~/dev/p5-net-libssh`'s board —
  never an edit there.
- **`.claude/` is git-ignored except for a whitelist** in `.gitignore`
  (`settings.json`, `agents/`, `skills/`, `rules/`, `hooks/`). A new directory
  under `.claude/` is invisible to git until whitelisted — check
  `git status --short` after adding one.

.claude/skills/perl-alien/references/alienfile.md  view on Meta::CPAN

# The alienfile in detail

## Interpolation

`%{…}` is expanded by Alien::Build against helpers and install properties:

| Token | Is |
|---|---|
| `%{cmake}`, `%{make}`, `%{perl}` | the tool as this build should invoke it |
| `%{.install.prefix}` | the staging prefix the built library must land in |
| `%{.install.extract}` | the extracted source directory |
| `%{.install.download}` | the downloaded file, before extraction |
| `%{.install.stage}` | the staging directory the build installs into |
| `%{.runtime.prefix}` | the final prefix, at runtime |

.claude/skills/perl-xs/references/build-and-test.md  view on Meta::CPAN

xsubpp is `ExtUtils::ParseXS`, versioned independently of Perl and upgradable from
CPAN — so an XS feature gated on an xsubpp version is a *toolchain* requirement, not
a Perl one:

```bash
perl -MExtUtils::ParseXS -e 'print "$ExtUtils::ParseXS::VERSION\n"'
```

A typemap that needs a minimum states `REQUIRE: 3.60` on its first line. Without
that line, a construct like `${type}` expanding `::` to `__` silently produces
uncompilable C on older toolchains.

## Reading the generated C

When a compile error points into generated code, generate it directly and read it:

```bash
perl -MExtUtils::ParseXS -e \
  'ExtUtils::ParseXS->new->process_file(filename=>"Foo.xs", output=>"/tmp/gen.c",
                                        typemap=>"typemap")'

.claude/skills/perl-xs/references/typemap.md  view on Meta::CPAN

typedef FOO_Conn   *Foo;             /* the class name as a C identifier */
typedef FOO_Handle *Foo__Handle;     /* :: → __ is xsubpp's C-identifier form */
```

so `Foo::Handle self` in the signature needs no `*`, and the generated C sees
`Foo__Handle self`.

## One entry per type, not one generic entry

A single generic `T_MAGICEXT` entry that writes `&${type}_magic` looks like the
obvious deduplication. It relies on xsubpp expanding `::` to `__` inside `${type}`,
**which only happens from xsubpp 3.60 on** — below that, `${type}` is still
`Foo::Handle`, which is not a C identifier, and the generated file will not compile.
A distribution supporting older toolchains spells the vtable pointer out per type
(and one that does not, states `REQUIRE: 3.60` at the top of the typemap).

## Standard entries worth knowing

| XS type | For |
|---|---|
| `T_IV` / `T_UV` / `T_NV` | plain integers and floats |