Skip to content

Commit

Permalink
clean up README for new changes
Browse files Browse the repository at this point in the history
  • Loading branch information
@truemedian @zhaozg
truemedian authored and zhaozg committed Jul 4, 2024
1 parent c9afc10 commit bdb3d27
Showing 1 changed file with 51 additions and 118 deletions.
169 changes: 51 additions & 118 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
# luvi

[![Linux Build Status](https://github.com/luvit/luvi/actions/workflows/ci.yml/badge.svg)](https://github.com/luvit/luvi/actions/workflows/ci.yml)
[![Windows Build status](https://ci.appveyor.com/api/projects/status/h643wg5hkwsnu0wd/branch/master?svg=true)](https://ci.appveyor.com/project/racker-buildbot/luvi/branch/master)
[![Code Quality: Cpp](https://img.shields.io/lgtm/grade/cpp/g/luvit/luvi.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/luvit/luvi/context:cpp)
[![Total Alerts](https://img.shields.io/lgtm/alerts/g/luvit/luvi.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/luvit/luvi/alerts)
[![Build Status](https://github.com/luvit/luvi/actions/workflows/ci.yml/badge.svg)](https://github.com/luvit/luvi/actions/workflows/ci.yml)

A project in-between [luv][] and [luvit][].

Expand Down Expand Up @@ -34,12 +31,14 @@ luvi myapp -o mybinary --strip

## Main API

Your `main.lua` is run in a mostly stock [luajit][] environment with a few extra things added. This means you can use
the luajit [extensions][] including `DLUAJIT_ENABLE_LUA52COMPAT` features, which we turn on.
Your `main.lua` is run in either a mostly stock [lua][] or [luajit][] environment with a few extra things added. Luajit
is built with `LUAJIT_ENABLE_LUA52COMPAT` features turned on, and all luajit [extensions][] are available. Lua is built
with the `bit` library included, for parity with luajit.

### Libuv is baked in

The "uv" module contains bindings to [libuv][] as defined in the [luv][] project. Simply `require("uv")` to access it.
The "uv" module is also provided under the name "luv" for parity with luarocks, so `require("luv")` will also work.

Use this for file I/O, network I/O, timers, or various interfaces with the operating system. This lets you write fast
non-blocking network servers or frameworks. The APIs in [luv][] mirror what's in [libuv][] allowing you to add
Expand All @@ -48,6 +47,14 @@ whatever API sugar you want on top be it callbacks, coroutines, or whatever.
Just be sure to call `uv.run()` and the end of your script to start the event loop if you want to actually wait for any
events to happen.

[extensions]: http://luajit.org/extensions.html
[lua]: https://www.lua.org/
[luajit]: https://luajit.org/
[libuv]: https://github.com/joyent/libuv
[luv]: https://github.com/luvit/luv
[luvit]: https://luvit.io/
[derivatives]: http://virgoagent.com/

```lua
local uv = require('uv')

Expand Down Expand Up @@ -75,44 +82,19 @@ uv.run()

### Integration with C's main function

The raw `argc` and `argv` from C side is exposed as a **zero** indexed lua table of strings at `args`.
The raw `argc` and `argv` from C side is exposed as a **zero** indexed lua table of strings at `args`. The `0`-th
element is generally the name of the binary that was executed.

```lua
print("Your arguments were", args)
print("Your arguments were")
for i = 0, #args do
print(i, args[i])
end
```

The "env" module provides read/write access to your local environment variables via `env.keys`, `env.get`, `env.put`,
`env.set`, and `env.unset`.

```lua
local env = require('env')

-- Convert the module to a mutable magic table.
local environment = setmetatable({}, {
__pairs = function (table)
local keys = env.keys()
local index = 0
return function (...)
index = index + 1
local name = keys[index]
if name then
return name, table[name]
end
end
end,
__index = function (table, name)
return env.get(name)
end,
__newindex = function (table, name, value)
if value then
env.set(name, value, 1)
else
env.unset(name)
end
end
}))
```

If you return an integer from `main.lua` it will be your program's exit code.

### Bundle I/O
Expand All @@ -127,8 +109,8 @@ local files = bundle.readdir("")

#### bundle.stat(path)

Load metadata about a file in the bundle. This includes `type` ("file" or
"directory"), `mtime` (in ms since epoch), and `size` (in bytes).
Load metadata about a file in the bundle. This includes `type` ("file" or "directory"), `mtime` (in ms since epoch),
and `size` (in bytes).

If the file doesn't exist, it returns `nil`.

Expand All @@ -140,60 +122,39 @@ If the directory doesn't exist, it return `nil`.

#### bundle.readfile(path)

Read the contents of a file. Returns a string if the file exists and `nil` if
it doesn't.
Read the contents of a file. Returns a string if the file exists and `nil` if it doesn't.

### Utils
## Building from Source

There is also a "utils" module that has some useful debugging stuff like a colorized
pretty printer.
We maintain several [binary releases of luvi](https://github.com/luvit/luvi/releases) to ease bootstrapping of lit and
luvit apps.

```lua
local uv = require('uv')
local dump = require('utils').dump
-- Create a global p() function that pretty prints any values
-- to stdout using libuv's APIs
_G.p = function (...)
local n = select('#', ...)
local arguments = { ... }

for i = 1, n do
arguments[i] = dump(arguments[i])
end
The following platforms are actively supported and tested by the CI system:

local toWrite = table.concat(arguments, "\t") .. "\n"
uv.write(stdout, toWrite);
end
```
- Windows >= 10 (x86_64 / i386)
- Linux >= 3.10, glibc >= 2.17 OR musl >= 1.0 (x86_64 / i386 / aarch64)
- Debian 8+
- Ubuntu 13.10+
- Fedora 19+
- OSX 13+ (x86_64 / aarch64)

[extensions]: http://luajit.org/extensions.html
[luajit]: http://luajit.org/
[libuv]: https://github.com/joyent/libuv
[luv]: https://github.com/luvit/luv
[luvit]: https://luvit.io/
[derivatives]: http://virgoagent.com/
The following platforms are supported but not actively tested by the CI system:

## Building from Source
- Windows >= 8 (x86_64 / i386)
- OSX 11+ (x86_64 / aarch64)
- FreeBSD 12+

We maintain several [binary releases of luvi](https://github.com/luvit/luvi/releases) to ease bootstrapping of lit and
luvit apps.
Platform support is primarily based on libuv's [platform support](https://github.com/libuv/libuv/blob/v1.x/SUPPORTED_PLATFORMS.md).

The following platforms are supported:
Architecture support is primarily based on luajit's [platform support](https://luajit.org/luajit.html).

- Windows (x86_64 / i386)
- FreeBSD 10.1 (x86_64)
- Raspberry PI Raspbian (armv6)
- Raspberry PI 2 Raspbian (armv7)
- Debian 9 "Stretch" (x86_64)
- OSX 10.14 "Mojave" (x86_64)
### Build Dependencies

If you want to not wait for pre-built binaries and dive right in, building is based on CMake and is pretty simple.

### Build Dependencies

- Git
- CMake
- A C Compiler (visual studio on Windows)
- A C Compiler (Visual Studio 15+ OR MinGW on Windows)
- Perl (required for OpenSSL)
- NASM (required for OpenSSL ASM optimizations on Windows)

Expand All @@ -203,16 +164,18 @@ First clone this repo recursively.
git clone --recursive https://github.com/luvit/luvi.git
```

Then run the makefile inside it. (Note this assumes you have cmake in your path.)
If you're on windows, there is a `make.bat` file that works mostly like the unix
`Makefile`.
> [!IMPORTANT]
> If you're on windows, for all following steps you will need to be in a [Visual Studio Command Prompt](https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022).
>
> You will need to replace `make` with `nmake` in the following commands.
Then enter the directory and run the makefile inside it, which will assume you have all the dependencies installed,
primarily CMake.

Prior to building the `luvi` binary you must configure the version of `luvi`
that you want to build. Currently there are three versions:
Prior to building luvi you must configure the version of luvi that you want to build. Currently there are two versions:

- tiny: only the necessities; omits OpenSSL, LPeg, and lrexlib
- regular: the normal luvit experience; includes OpenSSL, lpeg and lrexlib
- regular-asm: includes OpenSSL's ASM optimizations
- `tiny`: only the necessities, includes only Lua, Libuv, miniz, and minimal luvi modules.
- `regular`: the normal luvit experience, includes OpenSSL, LPeg, and lrexlib.

```sh
cd luvi
Expand All @@ -221,7 +184,7 @@ make
make test
```

When that's done you should have a shiny little binary in `build/luvi`.
When that's done you should have a luvi binary in `build/luvi`.

```sh
$ ls -lh build/luvi
Expand Down Expand Up @@ -316,33 +279,3 @@ cmake \
-DOPENSSL_LIBRARIES=/usr/local/opt/openssl/lib \
..
```

## Holy Build

Executables across Linux distributions are not largely portable for various
differences. We can leverage the
[holy-build-box](https://github.com/phusion/holy-build-box) to create a
portable executable for i686 and x86_64 environments.

Note: If you are attempting this on OSX, please install GNU tar from homebrew:

```sh
brew install gnu-tar
```

To get started:

1. Create a docker machine:

```sh
docker-machine create --driver vmwarefusion --vmwarefusion-cpu-count 3 holy-build-box
eval $(docker-machine env holy-build-box)
```

2. Start the build

```sh
make linux-build
```

3. Results should be the current working directory.

0 comments on commit bdb3d27

Please sign in to comment.