1 files changed, 37 insertions, 0 deletions
diff --git a/docs/c-interoperability.md b/docs/c-interoperability.md
new file mode 100644
index 00000000..68a84342
--- /dev/null
+++ b/docs/c-interoperability.md
@@ -0,0 +1,37 @@
+# C Interoperability
+
+Tomo is intended to be used as a complete, standalone programming language, but
+it's also meant to be easy to integrate with existing C libraries. In order to
+make this possible, there are a few tools available.
+
+## Using C Libraries 
+
+In order to link against a compiled shared library, you can use `use libfoo.so`
+to cause Tomo to add `-l:libfoo.so` to the linker flags when compiling your
+final executable. You can also use `use <foo.h>` or `use "foo.h"` to cause Tomo
+to insert a corresponding `#include` when compiling your code.
+
+## Inline C Code
+
+As a final escape hatch, you can use `inline C` to add code that will be put,
+verbatim in the transpiled C code generated by Tomo. There are two forms: one
+that creates an expression value and one that creates a block that is executed
+without evaluating to anything:
+
+```tomo
+# Inline C block:
+inline C {
+    printf("This is just a block that is executed without a return value\n");
+}
+
+# Inline C expression (you must specify a type)
+val := inline C : Int32 {
+    int x = 1; x + 1
+}
+```
+
+Inline C expressions must specify a type and they can be [compound statement
+expressions](https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html). In
+other words, if an inline C expression has a type, it will be enclosed
+with `({ ...; })` so that you can put semicolon-terminated statements before
+the final expression in their own scope if you want.