[README] Improve README.

README.md

@@ -1,3 +1,120 @@
-# lua-osx
+Operating System eXtensions for Lua
+===================================
+
+A C module to provide a few fundamental system-specific facilities to the
+Lua language.
+
+This library provides means to:
+- traverse and filter directory contents;
+- retrieve basic file information (type, size, modification time, ...);
+- create directories;
+- advanced file interaction (change size and mode, lock files, advise kernel on file access pattern, ...).
+
+## Why?
+
+Mainline Lua only exposes functionality when directly
+available through the standard C library (with the notable exception of popen()).
+This is justified by the embeddable nature of Lua.
+
+Yet, a minimum degree of system-specific interaction is needed to complete
+basic to advanced general purpose scripting and programmatic tasks.
+**lua-osx** attempts to fill this gap.
+
+## Philosophy
+
+The library adheres the following these guidelines:
+* only provide essential and reasonably portable functionality;
+* integrate seamlessly with the official Lua library
+  (e.g. support Lua files as arguments, behave consistently with the Lua standard library);
+* avoid functionality only available in one system (e.g. providing a Linux-only function).
+
+These are intended to be general principles, exceptions may apply when justified.
+
+## Compatibility
+
+**lua-osx** is portable with most relevant Lua implementations, specifically it is
+tested on [PUC Rio Lua](https://www.lua.org) and [LuaJIT](https://luajit.org).
+Code is known to work on Linux and Windows, and it should be portable to any POSIX
+system (BSD and Mac).
+
+## Build and install
+
+**lua-osx** comes with a Makefile and a [LuaRocks]() file.
+
+Windows users should note that **lua-osx** does not support MSVC and never will.
+It requires a fairly modern C compiler with C11 support and minimal Unix-style
+shell tools. On Windows you may use MSYS with either MinGW or clang.
+
+### Using LuaRocks
+
+You can build and install **lua-osx** locally on for your user, by
+opening a shell in the project's root directory and issuing the following
+command:
+```sh
+$ luarocks build --local
+```
+
+Or alternatively build and install it system-wide with:
+```sh
+# luarocks build --global
+```
+
+### Building using Makefile
+
+**lua-osx** rock uses the project Makefile to do build the module.
+
+The Makefile may also be used stand-alone, and support a number
+of configurations to adapt to the different supported systems.
+These may be picked with the `CONFIG` variable.
+
+* **Building on GNU/Linux and regular Unix-like systems**
+
+  The regular Unix configuration is used by default, thus
+  you may simply run:
+  ```sh
+  $ make
+  ```
+
+  Or use the extended (equivalent) form:
+  ```sh
+  $ make CONFIG=config.unix
+  ```
+
+* **Building on Windows**
+
+  You may build **lua-osx** using any fairly recent C compiler
+  with C11 support (e.g. MinGW or clang), and Unix-style shell
+  utilities and `make` (e.g. MSYS and GNU make).
+  ```sh
+  $ make CONFIG=config.win
+  ```
+
+* **Building on Mac**
+
+  To build **lua-osx** on Mac select the `config.macosx` configuration:
+  ```sh
+  $ make CONFIG=config.macosx
+  ```
+
+### Installing using Makefiles
+
+**lua-osx** Makefile supports your average `clean`, `install` and `uninstall`
+targets, thus you can install **lua-osx** system wide by running:
+```sh
+# make install
+```
+
+## Documentation
+
+Currently in progress, stay tuned!
+
+## Similar Projects
+
+* [LuaFileSystem](https://lunarmodules.github.io/luafilesystem)
+
+## License
+
+**lua-osx** is free software.
+You can redistribute and/or modify it under the terms of the GNU Lesser General Public License.
+See [LICENSE file](LICENSE) for details.
 
-Portable low-level filesystem and OS interface for Lua.