From 76120ce6388085c529d64e6bf6529dddb5681644 Mon Sep 17 00:00:00 2001 From: Matthew Heon Date: Mon, 30 Sep 2019 08:56:38 -0400 Subject: Move derivitive doc so it won't be treated as a manpage Anything with the .md suffix in docs/ gets compiled into a manpage, so let's get things that aren't manpages out of there. This isn't precisely a tutorial, but it seems like the next best place. Signed-off-by: Matthew Heon --- docs/podman-derivative-api.md | 44 --------------------------------- docs/tutorials/podman-derivative-api.md | 44 +++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 44 deletions(-) delete mode 100644 docs/podman-derivative-api.md create mode 100644 docs/tutorials/podman-derivative-api.md diff --git a/docs/podman-derivative-api.md b/docs/podman-derivative-api.md deleted file mode 100644 index 0342bb740..000000000 --- a/docs/podman-derivative-api.md +++ /dev/null @@ -1,44 +0,0 @@ -# How to use libpod for custom/derivative projects - -libpod today is a Golang library and a CLI. The choice of interface you make has advantages and disadvantages. - -Running as a subprocess ---- - -Advantages: - - - Many commands output JSON - - Works with languages other than Golang - - Easy to get started - -Disadvantages: - - - Error handling is harder - - May be slower - - Can't hook into or control low-level things like how images are pulled - -Vendoring into a Go project ---- - -Advantages: - - - Significant power and control - -Disadvantages: - - - You are now on the hook for container runtime security updates (partially, `runc`/`crun` are separate) - - Binary size - - Potential skew between multiple libpod versions operating on the same storage can cause problems - -Varlink ---- - -Some code exists for this; splits the difference. Future uncertain. - -Making the choice ---- - -A good question to ask first is: Do you want users to be able to use `podman` to manipulate the containers created by your project? -If so, that makes it more likely that you want to run `podman` as a subprocess. If you want a separate image store and a fundamentally -different experience; if what you're doing with containers is quite different from those created by the `podman` CLI, -that may drive you towards vendoring. \ No newline at end of file diff --git a/docs/tutorials/podman-derivative-api.md b/docs/tutorials/podman-derivative-api.md new file mode 100644 index 000000000..0342bb740 --- /dev/null +++ b/docs/tutorials/podman-derivative-api.md @@ -0,0 +1,44 @@ +# How to use libpod for custom/derivative projects + +libpod today is a Golang library and a CLI. The choice of interface you make has advantages and disadvantages. + +Running as a subprocess +--- + +Advantages: + + - Many commands output JSON + - Works with languages other than Golang + - Easy to get started + +Disadvantages: + + - Error handling is harder + - May be slower + - Can't hook into or control low-level things like how images are pulled + +Vendoring into a Go project +--- + +Advantages: + + - Significant power and control + +Disadvantages: + + - You are now on the hook for container runtime security updates (partially, `runc`/`crun` are separate) + - Binary size + - Potential skew between multiple libpod versions operating on the same storage can cause problems + +Varlink +--- + +Some code exists for this; splits the difference. Future uncertain. + +Making the choice +--- + +A good question to ask first is: Do you want users to be able to use `podman` to manipulate the containers created by your project? +If so, that makes it more likely that you want to run `podman` as a subprocess. If you want a separate image store and a fundamentally +different experience; if what you're doing with containers is quite different from those created by the `podman` CLI, +that may drive you towards vendoring. \ No newline at end of file -- cgit v1.2.3-54-g00ecf