[README] Improve README.
This commit is contained in:
parent
e67135cbab
commit
405da8b141
121
README.md
121
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.
|
|
Loading…
Reference in New Issue