diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9d7bf3a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,36 @@
+# ImmuTable
+
+This is a native Lua library that allows the creation of immutable tables.
+
+## Build
+
+`make LUA=/path/to/lua`
+or for LuaJIT: `make LUA=/path/to/lua LUASUFFIX=jit`
+
+## Usage
+
+```
+local immutable = require "immutable"
+local Vec2 = immutable({"x","y"}, {
+    len2=function(self)
+        return self.x*self.x + self.y*self.y
+    end,
+    is_a_vec2 = true,
+}, {
+    __add=function(self, other)
+        local cls = getmetatable(self)
+        return cls(self.x+other.x, self.y+other.y)
+    end,
+    __tostring=function(self)
+        return "Vec2("..tostring(self.x)..", "..tostring(self.y)..")"
+    end,
+})
+local v = Vec2(2, 3)
+assert(v.x == 2 and v.y == 3)
+local v2 = v + Vec2(0, 1)
+assert(v2 == Vec2(2, 4))
+local t = {[v2]='yep'}
+assert(t[Vec2(2,4)] == 'yep')
+assert(Vec2(2,0):len2() == 4)
+assert(Vec2(2,0).is_a_vec2)
+```