summaryrefslogtreecommitdiff
path: root/docs/tutorials/podman-derivative-api.md
diff options
context:
space:
mode:
authorMatthew Heon <mheon@redhat.com>2019-09-30 08:56:38 -0400
committerMatthew Heon <mheon@redhat.com>2019-09-30 08:56:38 -0400
commit76120ce6388085c529d64e6bf6529dddb5681644 (patch)
tree2cd1c36e9a75c2d382d013481ab6d8917d6b57a1 /docs/tutorials/podman-derivative-api.md
parent01b7af8ee9b3df1439c4da109ba11e7410108dab (diff)
downloadpodman-76120ce6388085c529d64e6bf6529dddb5681644.tar.gz
podman-76120ce6388085c529d64e6bf6529dddb5681644.tar.bz2
podman-76120ce6388085c529d64e6bf6529dddb5681644.zip
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 <mheon@redhat.com>
Diffstat (limited to 'docs/tutorials/podman-derivative-api.md')
-rw-r--r--docs/tutorials/podman-derivative-api.md44
1 files changed, 44 insertions, 0 deletions
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