[README] Improve README.

This commit is contained in:
Lorenzo Cogotti 2022-12-13 11:35:30 +01:00
parent e67135cbab
commit 405da8b141
1 changed files with 119 additions and 2 deletions

121
README.md
View File

@ -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.