Rebrand to ckb-lua-vm, add comments on command line arguments (#13)

* add docs for command line arguments

* remove command line argument -l

* rename ckb-lua to ckb-lua-vm

README.md

@@ -1,6 +1,6 @@
-[![CI](https://github.com/nervosnetwork/ckb-lua/actions/workflows/ci.yml/badge.svg)](https://github.com/nervosnetwork/ckb-lua/actions/workflows/ci.yml)
+[![CI](https://github.com/nervosnetwork/ckb-lua-vm/actions/workflows/ci.yml/badge.svg)](https://github.com/nervosnetwork/ckb-lua-vm/actions/workflows/ci.yml)
 
-# ckb-lua
+# ckb-lua-vm
 A project to help developers writing script in Lua on [CKB-VM](https://github.com/nervosnetwork/ckb-vm).
 
 
@@ -28,3 +28,16 @@ Use `build/libckblua.so` as a dynamic library. See [dylib.md](./docs/dylib.md) f
 2. Standalone
 
 Use `build/lua-loader` as a script. Require hacking for further requirement.
+
+## Command Line Arguments
+
+A couple of arguments may be passed to ckb-lua-vm.
+If no command line arguments is passed to ckb-lua-vm, ckb-lua-vm will run the script contained in cell data,
+which is assumed to be a valid exectuable lua file.
+
+The following are the supported command line arguments.
+To test the `ADDITIONAL_ARGUMENTS` locally, we can run `ckb-debugger --bin ./build/lua-loader.debug -- ADDITIONAL_ARGUMENTS`
+
+- `-e` is used to evaluate some lua script. For example, running `ckb-debugger --bin ./build/lua-loader.debug -- -e 'print("abcdefg")'` will print out `abcdefg` in to console.
+- `-f` is used to enable [file system access](./docs/fs.md). For example, running `ckb-debugger --bin ./build/lua-loader.debug -- -f` would evaluate the `main.lua` file within the file system in the cell data.
+- `-r` is used to execute coded loaded from ckb-debugger. For example, running `ckb-debugger ---read-file strings.lua --bin ./build/lua-loader.debug -- -r` will execute the lua file `strings.lua`. Normally, ckb-lua-vm can not read files from local file system, we add this parameter (along with the `--read-file` parameter of `ckb-debugger`) to facilitate testing of running local lua files.

docs/fs.md

@@ -1,4 +1,4 @@
-To faciliate the sharing of lua modules, we created a file system called Simple Lua File System that can be mounted by ckb-lua.
+To faciliate the sharing of lua modules, we created a file system called Simple Lua File System that can be mounted by ckb-lua-vm.
 Files within the file system may be made available for lua scripts to read and execute,
 e.g. running `require('mymodule')` and `io.open('myfile')`.
 The file system can be stored in any cell whose data are reachable from lua scripts,

docs/spawn.md

@@ -7,21 +7,21 @@ when the availablity of spawn syscall changes.
 | mainnet | NOT ready |
 | testnet | NOT ready |
 
-# Running ckb-lua as a subprocess to the main script
-There are quite a few benefits in running ckb-lua as a subprocess to the main script.
-- The main script's context is saved, and can continue to run when ckb-lua exits.
-- The ckb-lua instances are called with command line arguments which can be used to differentiate different tasks.
+# Running ckb-lua-vm as a subprocess to the main script
+There are quite a few benefits in running ckb-lua-vm as a subprocess to the main script.
+- The main script's context is saved, and can continue to run when ckb-lua-vm exits.
+- The ckb-lua-vm instances are called with command line arguments which can be used to differentiate different tasks.
 - Ckb-lua may return data of any format by the function `ckb.set_content`.
 
-To demostrate how to extend the capabilities of a main script with ckb-lua, we provide
-an example (an admittedly contrived one) that spawn a ckb-lua subprocess which simply concatenate
+To demostrate how to extend the capabilities of a main script with ckb-lua-vm, we provide
+an example (an admittedly contrived one) that spawn a ckb-lua-vm subprocess which simply concatenate
 the command line arguments and return the result to the main script. 
 
 [The main script of this example](../examples/spawn.c) is written in c.
 This program can be built with `make all-via-docker`. Afterwards, you may run it
 with `make -C tests/test_cases spawnexample` which requries [this branch of ckb-standalone-debugger](https://github.com/mohanson/ckb-standalone-debugger/tree/syscall_spawn).
 
-The main script first reserves some memory for the sub-contract, and then invokes ckb-lua with
+The main script first reserves some memory for the sub-contract, and then invokes ckb-lua-vm with
 the command line arguments `"-e" "local m = arg[2] .. arg[3]; ckb.set_content(m)" "hello" "world"`
 which evaluates the lua code `local m = arg[2] .. arg[3]; ckb.set_content(m)`.
 

lua-loader/lua-cell-fs.c

@@ -1,6 +1,2 @@
 #include "../include/ckb_cell_fs.c"
 #include "lua-cell-fs-test.c"
-
-static int run_from_file_system(lua_State *L) {
-    return run_file_system_tests(L);
-}

lua-loader/lua-ckb.c

@@ -675,7 +675,7 @@ int lua_ckb_exit(lua_State *L) {
         int code = lua_get_int_code(L);
         ckb_exit(code);
     } else {
-        luaL_error(L, "exit in ckb-lua is not enabled");
+        luaL_error(L, "exit in ckb-lua-vm is not enabled");
     }
     return 0;
 }
@@ -814,7 +814,7 @@ int lua_ckb_load_header_by_field(lua_State *L) {
 }
 
 int lua_ckb_spawn(lua_State *L) {
-    printf("spawn is currently not implementd in ckb-lua\n");
+    printf("spawn is currently not implementd in ckb-lua-vm\n");
     lua_pushinteger(L, LUA_ERROR_NOT_IMPLEMENTED);
     return 1;
 }

lua-loader/lua-loader.c

@@ -326,7 +326,6 @@ static int pushargs(lua_State *L) {
 #define has_r 4     /* -r, to run scripts, with ability to load local files */
 #define has_f 16    /* -f, to enable file system support */
 #define has_t 32    /* -t, for file system tests */
-#define has_l 64 /* -l, to run scripts, without ability to load local files */
 /*
 ** Traverses all arguments from 'argv', returning a mask with those
 ** needed before running any Lua code (or an error code if it finds
@@ -347,9 +346,6 @@ static int collectargs(char **argv, int *first) {
             case 'r':
                 args |= has_r;
                 break;
-            case 'l':
-                args |= has_l;
-                break;
             case 'f':
                 args |= has_f;
                 break;
@@ -378,10 +374,9 @@ int read_file(char *buf, int size) {
     return ret;
 }
 
-// Load the file given from syscall, may optionally enable access to local files
-// by setting local_access_enabled to non-zero.
-static int run_from_file(lua_State *L, int local_access_enabled) {
-    enable_local_access(local_access_enabled);
+// Load the file given from syscall.
+static int run_from_file(lua_State *L) {
+    enable_local_access(1);
     char buf[1024 * 512];
     int count = read_file(buf, sizeof(buf));
     if (count < 0 || count == sizeof(buf)) {
@@ -448,11 +443,11 @@ static int pmain(lua_State *L) {
     }
     if (args & has_t) {
         enable_fs_access(1);
-        ret = run_from_file_system(L);
+        ret = run_file_system_tests(L);
         goto exit;
     }
-    if (args & has_r || args & has_l) {
-        ret = run_from_file(L, (args & has_r) == has_r);
+    if (args & has_r) {
+        ret = run_from_file(L);
         goto exit;
     }
     ret = load_lua_code_from_cell_data(L);

tests/official/main.lua

@@ -443,7 +443,7 @@ NoRun("unrecognized option '-vv'", "lua -vv")
 NoRun("unrecognized option '-iv'", "lua -iv")
 NoRun("'-e' needs argument", "lua -e")
 NoRun("syntax error", "lua -e a")
-NoRun("'-l' needs argument", "lua -l")
+-- NoRun("'-l' needs argument", "lua -l")
 
 
 if T then   -- test library?

tests/test_cases/tests_rust/Cargo.toml

@@ -1,5 +1,5 @@
 [package]
-name = "ckb-lua-tests"
+name = "ckb-lua-vm-tests"
 version = "0.1.0"
 authors = ["Nervos Core Dev <dev@nervos.org>"]
 edition = "2021"

tests/test_cases/tests_rust/src/tests/lib_ckb_lua.rs → tests/test_cases/tests_rust/src/tests/lib_ckb_lua_vm.rs

@@ -31,8 +31,8 @@ fn debug_printer(script: &Byte32, msg: &str) {
 fn gen_tx(dummy: &mut DummyDataLoader) -> TransactionView {
     let mut rng = <StdRng as SeedableRng>::from_seed([42u8; 32]);
 
-    // setup lib_ckb_lua dep
-    let lib_ckb_lua_out_point = {
+    // setup lib_ckb_lua_vm dep
+    let lib_ckb_lua_vm_out_point = {
         let contract_tx_hash = {
             let mut buf = [0u8; 32];
             rng.fill(&mut buf);
@@ -41,17 +41,17 @@ fn gen_tx(dummy: &mut DummyDataLoader) -> TransactionView {
         OutPoint::new(contract_tx_hash, 0)
     };
     // dep contract code
-    let lib_ckb_lua_cell = CellOutput::new_builder()
+    let lib_ckb_lua_vm_cell = CellOutput::new_builder()
         .capacity(
             Capacity::bytes(LIB_CKB_LUA_BIN.len())
                 .expect("script capacity")
                 .pack(),
         )
         .build();
-    let lib_ckb_lua_cell_data_hash = CellOutput::calc_data_hash(&LIB_CKB_LUA_BIN);
+    let lib_ckb_lua_vm_cell_data_hash = CellOutput::calc_data_hash(&LIB_CKB_LUA_BIN);
     dummy.cells.insert(
-        lib_ckb_lua_out_point.clone(),
-        (lib_ckb_lua_cell, LIB_CKB_LUA_BIN.clone()),
+        lib_ckb_lua_vm_out_point.clone(),
+        (lib_ckb_lua_vm_cell, LIB_CKB_LUA_BIN.clone()),
     );
 
     // setup dylib_test dep
@@ -86,7 +86,7 @@ fn gen_tx(dummy: &mut DummyDataLoader) -> TransactionView {
                 .dep_type(DepType::Code.into())
                 .build(),
             CellDep::new_builder()
-                .out_point(lib_ckb_lua_out_point)
+                .out_point(lib_ckb_lua_vm_out_point)
                 .dep_type(DepType::Code.into())
                 .build(),
         ])
@@ -104,9 +104,9 @@ fn gen_tx(dummy: &mut DummyDataLoader) -> TransactionView {
     };
     let out_point = OutPoint::new(previous_tx_hash, 0);
 
-    let mut buf = BytesMut::with_capacity(2 + lib_ckb_lua_cell_data_hash.as_slice().len() + 1);
+    let mut buf = BytesMut::with_capacity(2 + lib_ckb_lua_vm_cell_data_hash.as_slice().len() + 1);
     buf.extend_from_slice(&[0x00u8; 2]);
-    buf.extend_from_slice(lib_ckb_lua_cell_data_hash.as_slice());
+    buf.extend_from_slice(lib_ckb_lua_vm_cell_data_hash.as_slice());
     buf.put_u8(ScriptHashType::Data1.into());
     let args = buf.freeze();
 

tests/test_cases/tests_rust/src/tests/mod.rs

@@ -1,4 +1,4 @@
-mod lib_ckb_lua;
+mod lib_ckb_lua_vm;
 
 use ckb_traits::{CellDataProvider, HeaderProvider};
 use ckb_types::{