cpybkc

Cpybkc 🔗

Cpybkc is one cpybkc image, plus the coordinates for resolving images related to it.

A function on it is a builder returning a new Cpybkc, a terminal that runs something, or an accessor handing back what was resolved, so a call chain reads as the image being assembled and then used; nothing here mutates.

generate() 🔗

Generate runs cpybkc over a project and hands back the project as it should now be committed:

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  generate --source . export --path .

Nothing is written to the host. The Directory that comes back is a value like any other, and exporting it is the caller’s separate, explicit step — which is also what disposes of the ownership problem a bind mount has, where generated files land owned by whichever UID the container ran as and a host user who is not that UID owns none of their own project. Dagger’s export writes as the person running it, so the image’s pinned user never reaches the host.

What comes back is the whole project directory, not only the files a generator produced. A generator’s output lands where the manifest says, which is ordinarily inside the source tree, and a run also prunes what a previous run generated and no longer would — so the generated files alone cannot express half of what a run did. generate --source . export --path . is therefore the ordinary use, and it is a full statement of the run rather than an overlay that leaves deletions behind.

Return Type

Directory !

Arguments

dagger -m github.com/Zaba505/cpybkc/daggerverse/cpybkc@1d785b7223c913bd2b3ae0acd60e979995f7b0a9 call \
 generate --source DIR_PATHcontent_copy Copied! 

func (m *MyModule) Example(source *dagger.Directory) *dagger.Directory  {
	return dag.
			Cpybkc().
			Generate(source)
}content_copy Copied!

@function
def example(source: dagger.Directory) -> dagger.Directory:
	return (
		dag.cpybkc()
		.generate(source)
	)content_copy Copied!

@func()
example(source: Directory): Directory {
	return dag
		.cpybkc()
		.generate(source)
}content_copy Copied!

image() 🔗

Image is the image this module resolved and composed, for a caller who wants to do something with it other than what this module offers — run a cpybkc subcommand by hand, look at what is in it, publish a derived image holding their generators, or make it one variant of a multi-platform index:

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  image with-exec --use-entrypoint --args=--version stdout

Note the –use-entrypoint. The image’s entrypoint is the CLI and the literal value of it is not part of the contract (docs/container/SPEC.md, “The CLI’s own path is not part of the contract”), so an exec that named a path instead would be reaching for the one thing that document reserves the right to move.

Publishing the image elsewhere is a reasonable thing to do — it is the same image the registry served — but a copy is not a release of cpybkc and carries none of the signatures or attestations one does (docs/container/SPEC.md, “What a tag carries besides the image”), because those are attached to the digest this project published and not to the bytes.

Return Type

Container !

dagger -m github.com/Zaba505/cpybkc/daggerverse/cpybkc@1d785b7223c913bd2b3ae0acd60e979995f7b0a9 call \
 imagecontent_copy Copied! 

func (m *MyModule) Example() *dagger.Container  {
	return dag.
			Cpybkc().
			Image()
}content_copy Copied!

@function
def example() -> dagger.Container:
	return (
		dag.cpybkc()
		.image()
	)content_copy Copied!

@func()
example(): Container {
	return dag
		.cpybkc()
		.image()
}content_copy Copied!

init() 🔗

Init scaffolds a layout from copybooks and hands back the file to edit:

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  init --source . --copybook posting.cpy export --path ledger.sexpr

It is the first thing an adopter runs, before there is a manifest, a layout or a generator to speak of, and it is curated for that reason: the one invocation somebody has nothing to copy from is a poor place to make them assemble an argument vector by hand.

What comes back is not a valid layout and is not meant to be. init writes what the copybooks decide — a record per 01-level, an alternative per REDEFINES — and leaves the half no copybook holds as commented forms for a person to answer: which field discriminates, and in what order the records come. docs/cli/SPEC.md’s init section is what that file says and what it deliberately does not.

Nothing is written to the host, exactly as with Generate: the File that comes back is a value, and exporting it is the caller’s separate step. What it is called is theirs — this module writes the scaffold to a path of its own inside the container ([scaffoldPath]) that nothing was mounted into, so the run cannot land on something the caller already has, and the name it takes in their tree is the one they give export.

Where it goes is theirs within one constraint, and it is the one thing here a caller cannot infer from the signature. The scaffold names each copybook by the path it was given, which is relative to the root of source, and a layout’s own paths are relative to the layout — so the file belongs at that root, beside the copybooks it names. Exported into a subdirectory it is a layout whose copybook paths resolve nowhere, and nothing at export time will say so. A project that keeps its layout somewhere else moves the paths as it moves the file; they are the adopter’s to edit, like the rest of what init leaves blank.

The destination this module supplies is a file rather than a stream, so --out - is not offered here. A caller who wants the scaffold on standard output still has Run, which is the same arrangement –emit-ir has:

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  run --source . --args=init,--copybook,posting.cpy,--out,- stdout

Return Type

File !

Arguments

dagger -m github.com/Zaba505/cpybkc/daggerverse/cpybkc@1d785b7223c913bd2b3ae0acd60e979995f7b0a9 call \
 init --source DIR_PATH --copybook string1 --copybook string2content_copy Copied! 

func (m *MyModule) Example(source *dagger.Directory, copybook []string) *dagger.File  {
	return dag.
			Cpybkc().
			Init(source, copybook)
}content_copy Copied!

@function
def example(source: dagger.Directory, copybook: List[str]) -> dagger.File:
	return (
		dag.cpybkc()
		.init(source, copybook)
	)content_copy Copied!

@func()
example(source: Directory, copybook: string[]): File {
	return dag
		.cpybkc()
		.init(source, copybook)
}content_copy Copied!

run() 🔗

Run is the escape hatch: cpybkc invoked with an argument vector this module has no opinion about, in a container handed back whole.

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  run --source . --args=--emit-ir,- stdout

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  run --args=--help stdout

It exists so that Generate does not have to grow an argument every time docs/cli/SPEC.md’s flag table does. A flag that replaces the action rather than configuring it (–emit-ir is terminal: no generator runs and nothing is merged or pruned), one that may only appear beside another (–emit-ir-format without –emit-ir is a usage error), and one that answers a question about the program rather than about a project (–version, –help) are all things a command line states plainly and a set of Dagger arguments states badly.

A container rather than a directory, because the uncurated invocations are the ones whose answer is not a tree. –emit-ir may write to standard output, and –version and –help write nothing else at all; a Directory return would make the escape hatch unable to reach exactly the flags it exists for. A caller who does want the tree takes it from the container, where the project is still mounted at /src:

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  run --source . --args=--manifest,build/cpybkc.json \
  directory --path=/src export --path .

Nothing here is validated. A vector this module checked would be a second, unversioned reading of a contract the CLI already implements, and its diagnostics are better than anything guessed at from out here: what an unrecognised flag is, whether a flag may repeat and what a usage error exits with are all docs/cli/SPEC.md’s, and the exec’s failure carries them back verbatim.

Return Type

Container !

Arguments

dagger -m github.com/Zaba505/cpybkc/daggerverse/cpybkc@1d785b7223c913bd2b3ae0acd60e979995f7b0a9 call \
 run --args string1 --args string2content_copy Copied! 

func (m *MyModule) Example(args []string) *dagger.Container  {
	return dag.
			Cpybkc().
			Run(args)
}content_copy Copied!

@function
def example(args: List[str]) -> dagger.Container:
	return (
		dag.cpybkc()
		.run(args)
	)content_copy Copied!

@func()
example(args: string[]): Container {
	return dag
		.cpybkc()
		.run(args)
}content_copy Copied!

withGenerator() 🔗

WithGenerator adds one generator to the image by copying its executable out of a generator image:

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  with-generator --name hello --image ghcr.io/example/cpybkc-gen-hello:v1 \
  generate --source . export --path .

This is the whole of adding a generator without writing a Dockerfile. The file is taken out of the image at the path the base-image contract promises, which is what COPY --from does, and it works just as well for a generator image this project has never heard of — that is what image is for. Repeated calls compose, so a project whose manifest names three generators is three calls and one image.

With no image, the generator this project publishes for name is pulled: <repository>-gen-<name>:<version>, against the same coordinates the CLI image came from. A generator from one release beside a CLI from another is a pairing nobody tested, and defaulting to it is how somebody would end up in one without having said so.

The generator is pulled for the platform the container being composed into was resolved for, not for the engine’s. That is the whole of what this module does about multi-platform: composing an amd64 generator into an arm64 image produces an image that builds and pushes and then fails at exec with the kernel’s message rather than cpybkc’s, which is a long way from the call that caused it.

Return Type

Cpybkc !

Arguments

dagger -m github.com/Zaba505/cpybkc/daggerverse/cpybkc@1d785b7223c913bd2b3ae0acd60e979995f7b0a9 call \
 with-generator --name stringcontent_copy Copied! 

func (m *MyModule) Example(name string) *dagger.Cpybkc  {
	return dag.
			Cpybkc().
			Withgenerator(name)
}content_copy Copied!

@function
def example(name: str) -> dagger.Cpybkc:
	return (
		dag.cpybkc()
		.withgenerator(name)
	)content_copy Copied!

@func()
example(name: string): Cpybkc {
	return dag
		.cpybkc()
		.withGenerator(name)
}content_copy Copied!

withGeneratorExecutable() 🔗

WithGeneratorExecutable adds one generator to the image from an executable file, for a generator that ships no image — most often one the caller has just built in the same pipeline:

dagger call -m github.com/Zaba505/cpybkc/daggerverse/cpybkc \
  with-generator-executable --name hello --executable ./cpybkc-gen-hello \
  generate --source . export --path .

It is the generator author’s path, before there is anything of theirs to pull. Checking a plugin against a real cpybkc run is the first thing they need and the last thing a published image can give them.

The file lands as cpybkc-gen- whatever it was called before, because discovery is by filename and nothing inside the executable is consulted.

It has to be a statically linked native executable for the image’s platform, and that is the caller’s to meet rather than this module’s to check: it is the same requirement docs/container/SPEC.md’s worked example states as CGO_ENABLED=0, a File says nothing about what it is, and a dynamically linked or foreign-architecture generator fails at exec time with the kernel’s message rather than cpybkc’s. WithGenerator can check the platform half of that because a container states one; here there is nothing to read.

Return Type

Cpybkc !

Arguments

dagger -m github.com/Zaba505/cpybkc/daggerverse/cpybkc@1d785b7223c913bd2b3ae0acd60e979995f7b0a9 call \
 with-generator-executable --name string --executable file:pathcontent_copy Copied! 

func (m *MyModule) Example(name string, executable *dagger.File) *dagger.Cpybkc  {
	return dag.
			Cpybkc().
			Withgeneratorexecutable(name, executable)
}content_copy Copied!

@function
def example(name: str, executable: dagger.File) -> dagger.Cpybkc:
	return (
		dag.cpybkc()
		.withgeneratorexecutable(name, executable)
	)content_copy Copied!

@func()
example(name: string, executable: File): Cpybkc {
	return dag
		.cpybkc()
		.withGeneratorExecutable(name, executable)
}content_copy Copied!