The resty Command-Line Utility Demo
In this tutroial, we will demonstrate how to use the resty
command-line utility shipped with OpenResty.
1 | cd ~ |
It’s usually in this path.
We can check its version number with the -V
option.
1 | resty -V |
If you install OpenResty using our pre-built binary packages for Linux, then you should install the openresty-resty
package.
1 | dnf list installed openresty-resty |
Because it’s not in the openresty
main package.
It’s much easier to do “hello world” using a resty
command, for example.
1 | resty -e 'print("Hello World")' |
Note the -e
option.
Or run a Lua script on the terminal.
1 | echo 'print("Hello World")' > hello.lua |
So it is also a great way to write new command-line applications using OpenResty.
Nonblocking I/O is also possible here.
1 | time resty -e 'ngx.sleep(1) ngx.say("done")' |
Let’s connect to openresty.com’s 443 port using the cosocket API.
1 | resty -e 'local sock = ngx.socket.tcp() print(sock:connect("openresty.com", 443))' |
Or using light threads.
1 | resty -e 'ngx.thread.wait(ngx.thread.spawn(function () print("in thread!") end))' |
You can also use Lua modules easily. Let’s create a test
module.
1 | mkdir lua/ |
The lua/test.lua
file looks like this:
1 | local _M = {} |
And then we use the -I
option to add the lua/
directory to the Lua module search paths.
1 | resty -I lua/ -e 'require "test".hello()' |
Without the -I
option, it won’t find it.
1 | resty -e 'require "test".hello()' |
This is because the lua/
directory is not in the Lua module search paths by default.
Standard Lua modules can be loaded directly, like resty.shell
.
1 | resty -e 'local ok, stdout = require "resty.shell".run([[echo ok]]) print(stdout)' |
This module is for running abitrary shell commands nonblockingly.
We can also define lua shared memory dictionaries via the --shdict
option.
1 | resty --shdict 'dogs 10m' -e 'print(ngx.shared.dogs:set("age", 11))' |
Multiple shared dictionaries can be defined this way.
1 | resty --shdict 'dogs 7m' --shdict 'cats 5m' -e 'print(ngx.shared.dogs, " ", ngx.shared.cats)' |
It can also be handy to inject custom nginx configuration snippets.
1 | resty --http-conf 'lua_regex_match_limit 102400;' -e 'print "ok"' |
We can also play with LuaJIT’s JIT compiler.
Let’s create a hot Lua script.
1 | echo 'local a = 0 for i = 1, 1e8 do a = a + 1 end print(a)' > bench.lua |
And then disable the JIT compiler altogether.
1 | time resty -joff bench.lua |
For comparison, we can check how much faster when we enable the JIT compiler.
1 | time resty bench.lua |
Or we can check the compiled Lua code paths, or “traces”, with the -jv
option.
1 | resty -jv bench.lua |
Or with even more details like the compiled bytecode dump, IR code dump, as well as machine code dump.
1 | resty -jdump bench.lua |
You can always find all the supported features via the -h
option.
1 | resty -h |
Or refer to its documentation via the restydoc
utility.
1 | restydoc resty-cli |
If you install openresty
through our pre-built binary packages, then you should install the openresty-doc
or openresty-restydoc
package.
1 | dnf list installed openresty-doc |
We will have a closer look at the restydoc
utility in another dedicated video tutorial.
About This Article and Associated Video
This article and its associated video are both generated automatically from a simple screenplay file.
About The Author
Yichun Zhang is the creator of the OpenResty® open source project. He is also the founder and CEO of the OpenResty Inc. company. He contributed a dozen open source Nginx 3rd-party modules, quite some Nginx and LuaJIT core patches, and designed the OpenResty XRay platform.
Translations
We will provide a Chinese translation for this article on blog.openresty.com.cn. We also welcome interested readers to contribute translations in other natural languages as long as the full article is translated without any omissions. We thank them in advance.
We are hiring
We always welcome talented and enthusiastic engineers to join our team at OpenResty Inc.
to explore various open source software’s internals and build powerful analyzers and
visualizers for real world applications built atop the open source software. If you are
interested, please send your resume to talents@openresty.com
. Thank you!