summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOpenShift Merge Robot <openshift-merge-robot@users.noreply.github.com>2019-09-26 15:15:17 +0200
committerGitHub <noreply@github.com>2019-09-26 15:15:17 +0200
commitd76b21e27a7cef26865a05be02632ca76f9cf2ea (patch)
tree3db6fcb03abb92ce1b5a6d550cc88ae0e80c9ae6
parent3ed265c520eb4cea1e9157125dbff0e6a1b0b5f8 (diff)
parentaf00094558e0d16b56a7d4896a3c7ac250678498 (diff)
downloadpodman-d76b21e27a7cef26865a05be02632ca76f9cf2ea.tar.gz
podman-d76b21e27a7cef26865a05be02632ca76f9cf2ea.tar.bz2
podman-d76b21e27a7cef26865a05be02632ca76f9cf2ea.zip
Merge pull request #4109 from cgwalters/doc-custom-project
docs/podman-derivative-api.md: New file
-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