diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e010ce2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,75 @@
+# NVVM.jl
+
+Julia wrappers for generating PTX code with the NVIDIA NVVM library.
+
+
+## Quicks start
+
+Let's start with some dummy IR that conforms to NVVM IR v2 (aka. LLVM 7.0):
+
+```llvm
+target datalayout = "e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-i128:128:128-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"
+target triple = "nvptx64-nvidia-cuda"
+
+define void @kernel() {
+entry:
+    ret void
+}
+
+!nvvm.annotations = !{!0}
+!0 = !{void ()* @kernel, !"kernel", i32 1}
+
+!nvvmir.version = !{!1}
+!1 = !{i32 2, i32 0}
+```
+
+With NVVM.jl, you can compile this IR to PTX:
+
+```julia
+using NVVM
+
+prog = Program()
+add!(prog, ir)
+verify(ir)
+compile(prog)
+```
+
+```
+//
+// Generated by NVIDIA NVVM Compiler
+//
+// Compiler Build ID: CL-32688072
+// Cuda compilation tools, release 12.1, V12.1.105
+// Based on NVVM 7.0.1
+//
+
+.version 8.1
+.target sm_52
+.address_size 64
+
+	// .globl	kernel
+
+.visible .entry kernel()
+{
+	ret;
+}
+```
+
+To set compiler options, pass keyword arguments to `compile` or `verify`. You can use
+Julia keyword arguments to specify these options, using slightly user-friendlier syntax:
+
+```
+julia> compile(prog; arch=v"8.0", debug=true, opt=0, prec_sqrt=false)
+// Generated by NVIDIA NVVM Compiler
+.target sm_80
+...
+```
+
+
+## Limitations
+
+We always use the latest libNVVM, which means that you have to stick to the NVVM IR version
+it supports (currently v2.0), or use an older version of NVVM.jl. More problematically,
+that also means that the PTX version will be set to the latest ISA version (currently 8.1),
+which may not be supported by your driver. A feature request has been filed with NVIDIA
+to make this configurable.