From 90701bf0ef7386dfb1b05ef3da13782527ebf9ca Mon Sep 17 00:00:00 2001 From: Jeremy Baxter Date: Tue, 27 Feb 2024 18:43:59 +1300 Subject: [PATCH] readme: revise --- README.md | 109 +++++++++++++++++++++++++++--------------------------- 1 file changed, 55 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index f713bf5..1490731 100644 --- a/README.md +++ b/README.md @@ -1,62 +1,57 @@ ## callisto - standalone scripting platform for Lua 5.4 -Callisto extends Lua 5.4's standard library by adding new libraries and -facilities to the language. It includes a file system library to manage -and manipulate files, a process library to find active processes and -manipulate signals, and a JSON manipulation library (lua-cjson) *among -many more*. +Callisto extends Lua 5.4's standard library by adding new modules and +facilities to the interpreter. It includes a file system library to +manage and manipulate files and directories, a process library to find +active processes and manipulate signals, and a JSON manipulation +library (lua-cjson) *among many more*. It is a standalone interpreter designed for people using Lua as a -general scripting language, instead of using it embedded into another -application (what Lua was designed for). - -Before I made Callisto, I had to rely on luaposix for basic file system -manipulation and occasionally luasocket for HTTP plus lua-cjson for JSON -parsing. - -luaposix provides most of the necessary functions, but is generally -aimed towards people who already know how to use the POSIX APIs in C. +general scripting language, rather than using it embedded into another +program, which is what Lua was designed for. Perhaps you could think +of it as a replacement for Python. First and foremost, Callisto tries to be: - - an all-in-one zero-dependencies library for Lua that includes - most features people would need, out of the box - - a library that works and integrates well with Lua and its - standard library, and is easy to use for those who have no - experience with C + - a runtime environment for Lua that includes most features people + would need out of the box, all in one executable with zero + dependencies + - a library that works well and integrates well with the Lua language + and its standard library, and is easy to use for those who have no + prior experience with C Callisto relies on APIs specified in the POSIX specification; -therefore it does not support operating systems that do not -implement these APIs (like Microsoft Windows), only ones that -do (like Linux, macOS, and the BSDs). +therefore it cannot be used on operating systems that are not +POSIX-compliant (like Microsoft Windows). -## Dependencies +## portability -To build Callisto, you'll need nothing but a C compiler and `ar`. -The default C compiler is *cc* which is usually a symbolic link -to your system's default C compiler. This should be gcc on Linux, -and clang on most of the BSDs. If *cc* doesn't exist on your system, -override it by adding `CC=compiler` to make's command like -(replace `compiler` with the name or path to your C compiler) +To build Callisto, all you need is a C99 compiler. The configure +script will check for the presence of various compilers before +building, to decide which one to use. +The compilers checked are clang, followed by cc, followed by gcc. If +you have a compiler at a custom path that you would like to use over +the system C compiler, just pass `-c /path/to/compiler` to the +configure script before you build. The compiler must support gcc-like +command line arguments. -### Portability - -**Callisto has zero runtime dependencies**, unless you built it with -support for GNU libreadline.* Lua 5.4 is statically linked in. -This means that the same binary will likely work across different Linux -distributions/versions. The only strictly required library is libc -which is available on all systems. +Callisto has zero runtime dependencies, unless you built it with +support for GNU libreadline*. Lua 5.4 is statically linked in. This +means that the same binary will work across different Linux +distributions. *libreadline support can be enabled at build time, but is disabled by default. To force building with libreadline support, pass the `-wreadline` flag to the configure script. -## Installation +## installation -Callisto is distributed as source-only, but it's not hard to compile. +Callisto is distributed as source-only, but it's very easy to build it +yourself. Just make sure you have a compiler such as gcc installed, as +well as git for downloading the source code and make for compiling. -First, get the source code using one of the tarballs found in -the [Releases](https://github.com/jtbx/callisto/releases) page. -Untar it then enter the directory with Callisto's source code. +First, obtain a copy of the source code using the following command: + + git clone https://github.com/jtbx/callisto After that, run @@ -65,8 +60,9 @@ After that, run to compile Callisto and all its dependencies. -To install it, run `make install` as the root user in the source code directory -to install Callisto and its shared library. +To install it, run `make install` as the root user in the source code +directory. If you choose not to install it, you can still invoke it in +the current directory. ### Arch Linux @@ -80,22 +76,27 @@ If you use Nix, you can use the flake: nix profile install github:jtbx/callisto -## Usage +## usage -The standalone Callisto interpreter is called `csto`. Running it -will start a REPL so you can execute chunks of code interactively. +The standalone Callisto interpreter is called `csto`. This is the main +way to run Lua programs using the Callisto libraries. Running it +without arguments will start a read-eval-print loop so you can execute +chunks of code interactively. csto works just like the standalone Lua 5.4 interpreter. To execute -a file, run `csto file` where *file* is the name of the file containing -code that you want to run. Alternatively, you can put `#!/usr/bin/env csto` -at the top of your script, run `chmod +x` on it, and then you can run the -script as if it was a standalone executable, for example `./yourscript.lua`. +code in a file, run `csto file` where *file* is the name of the file +containing code you want to run. -## Documentation +Alternatively, put `#!/usr/bin/env csto` at the top of your script, +make it executable with `chmod +x`, and then you can run the script as +if it was a standalone executable, for example `./script.lua`. -Docs can be found here: +## documentation + +Library documentation can be found here: https://jtbx.github.io/callisto/doc -## Contributing +## contributing -Pop me an email with your patch at jtbx@disroot.org or open a Github pull request. +Drop me an email with your patch at jtbx@disroot.org or open a Github +pull request. You can optionally read the style.md document :)