summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorColin Walters <walters@verbum.org>2019-09-25 17:26:56 +0000
committerColin Walters <walters@verbum.org>2019-09-26 12:06:40 +0000
commitaf00094558e0d16b56a7d4896a3c7ac250678498 (patch)
tree35f4fb372feaa765e70482f093c55cf6f2d2400b
parent8ab3c86aa19d4851ee31a764becb7cbc8c1e9c07 (diff)
downloadpodman-af00094558e0d16b56a7d4896a3c7ac250678498.tar.gz
podman-af00094558e0d16b56a7d4896a3c7ac250678498.tar.bz2
podman-af00094558e0d16b56a7d4896a3c7ac250678498.zip
docs/podman-derivative-api.md: New file
https://github.com/debarshiray/toolbox/ was planning to vendor libpod which I disagreed with. Let's document the advantages/disadvantages as they exist today. Signed-off-by: Colin Walters <walters@verbum.org>
-rw-r--r--docs/podman-derivative-api.md44
1 files changed, 44 insertions, 0 deletions
diff --git a/docs/podman-derivative-api.md b/docs/podman-derivative-api.md
new file mode 100644
index 000000000..0342bb740
--- /dev/null
+++ b/docs/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