Merge branch 'teal_test' into 'master'

Teal declarations

See merge request OpenMW/openmw!2529

.gitlab-ci.yml

@@ -134,6 +134,18 @@ Clang_Format:
   script:
     - CI/check_clang_format.sh
 
+Teal:
+  stage: checks
+  extends: .Ubuntu_Image
+  before_script:
+    - apt-get update
+    - apt-get -y install curl wget make build-essential libreadline-dev git-core zip unzip
+  script:
+    - CI/teal_ci.sh
+  artifacts:
+    paths:
+      - teal_declarations.zip
+
 Ubuntu_GCC_Debug:
   extends: .Ubuntu
   cache:

CI/teal_ci.sh

@@ -0,0 +1,15 @@
+docs/source/install_luadocumentor_in_docker.sh
+PATH=$PATH:~/luarocks/bin
+
+pushd .
+echo "Install Teal Cyan"
+git clone https://github.com/teal-language/cyan.git --depth 1
+cd cyan
+luarocks make cyan-dev-1.rockspec
+
+LUAROCKS=~/luarocks/bin
+export LUAROCKS
+popd
+
+scripts/generate_teal_declarations.sh ./teal_declarations
+zip teal_declarations.zip -r teal_declarations

docs/source/generate_luadoc.sh

@@ -7,7 +7,7 @@ DOCUMENTOR_PATH=~/.luarocks/bin/openmwluadocumentor
 
 if [ ! -x $DOCUMENTOR_PATH ]; then
     if [ -f /.dockerenv ] || [ -f /home/docs/omw_luadoc_docker ]; then
-        . install_luadocumentor_in_docker.sh
+        ./install_luadocumentor_in_docker.sh
     else
         # running on Windows?
         DOCUMENTOR_PATH="$APPDATA/LuaRocks/bin/openmwluadocumentor.bat"
@@ -20,13 +20,12 @@ fi
 
 rm -f $OUTPUT_DIR/*.html
 
+data_paths=$($DOCS_SOURCE_DIR/luadoc_data_paths.sh)
+
 cd $FILES_DIR/lua_api
 $DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR openmw/*lua
-
 cd $FILES_DIR/data
-$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR openmw_aux/*lua
+for path in $data_paths
-$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/ai.lua
+do
-$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/playercontrols.lua
+  $DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR $path
-$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/camera/camera.lua
+done
-$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/mwui/init.lua
-$DOCUMENTOR_PATH -f doc -d $OUTPUT_DIR scripts/omw/settings/player.lua

docs/source/install_luadocumentor_in_docker.sh

@@ -14,21 +14,22 @@ cd ~
 PATH=$PATH:~/lua-5.1.5/src
 
 echo "Install luarocks"
-wget https://luarocks.org/releases/luarocks-2.4.2.tar.gz
+luarocksV="3.9.2"
-tar zxpf luarocks-2.4.2.tar.gz
+wget https://luarocks.org/releases/luarocks-$luarocksV.tar.gz
-rm luarocks-2.4.2.tar.gz
+tar zxpf luarocks-$luarocksV.tar.gz
-cd luarocks-2.4.2/
+rm luarocks-$luarocksV.tar.gz
+cd luarocks-$luarocksV/
 ./configure --with-lua-bin=$HOME/lua-5.1.5/src --with-lua-include=$HOME/lua-5.1.5/src --prefix=$HOME/luarocks
 make build
 make install
 cd ~
-rm -r luarocks-2.4.2
+rm -r luarocks-$luarocksV
 PATH=$PATH:~/luarocks/bin
 
 echo "Install openmwluadocumentor"
 git clone https://gitlab.com/ptmikheev/openmw-luadocumentor.git
-cd openmw-luadocumentor/luarocks
+git checkout 78577b255d19a1f4f4f539662e00357936b73c33
-luarocks --local pack openmwluadocumentor-0.2.0-1.rockspec
+cd openmw-luadocumentor
-luarocks --local install openmwluadocumentor-0.2.0-1.src.rock
+luarocks make luarocks/openmwluadocumentor-0.2.0-1.rockspec
 cd ~
 rm -r openmw-luadocumentor

docs/source/luadoc_data_paths.sh

@@ -0,0 +1,9 @@
+paths=(
+  openmw_aux/*lua
+  scripts/omw/ai.lua
+  scripts/omw/playercontrols.lua
+  scripts/omw/camera/camera.lua
+  scripts/omw/mwui/init.lua
+  scripts/omw/settings/player.lua
+)
+printf '%s\n' "${paths[@]}"

docs/source/reference/lua-scripting/index.rst

@@ -12,4 +12,5 @@ OpenMW Lua scripting
 
     overview
     api
+    teal
 

docs/source/reference/lua-scripting/overview.rst

@@ -7,7 +7,10 @@ Language and sandboxing
 OpenMW supports scripts written in Lua 5.1 with some extensions (see below) from Lua 5.2.
 There are no plans to switch to any newer version of the language, because newer versions are not supported by LuaJIT.
 
-Here are starting points for learning Lua:
+.. note::
+  There are also experimental declarations available for Teal, a typed dialect of Lua. see :ref:`Teal` for more details.
+
+Here are some starting points for learning Lua:
 
 - `Programing in Lua <https://www.lua.org/pil/contents.html>`__ (first edition, aimed at Lua 5.0)
 - `Lua 5.1 Reference Manual <https://www.lua.org/manual/5.1/>`__

docs/source/reference/lua-scripting/teal.rst

@@ -0,0 +1,45 @@
+####
+Teal
+####
+
+What is Teal?
+=============
+
+Teal is a typed dialect of Lua. `Teal's Github repository <https://github.com/teal-language/tl>`_.
+
+Teal compiles into Lua, so you can use it in any Lua 5.1+ runtime. If you are familiar with TypeScript, Teal is to Lua what TypeScript is to JavaScript.
+You can find the basics of the syntax and justification for typed Lua in the `Teal tutorial <https://github.com/teal-language/tl/blob/master/docs/tutorial.md>`_.
+
+Teal's syntax is mostly the same as Lua, but with additional type declarations and annotations.
+It will help you catch many mistakes before even running a script, and provide confidence about large code changes.
+
+Using the type checker
+======================
+
+To compile your ``.tl`` files into ``.lua`` files, install `Cyan, Teal's build system <https://github.com/teal-language/cyan>`_.
+
+Create a directory for your project, with a ``tlconfig.lua`` file inside.
+All of your scripts (i. e. the ``scripts`` directory) should be within this directory.
+``tlconfig.lua`` configures the Teal build system and compiler, see the `complete list here <https://github.com/teal-language/tl/blob/master/docs/compiler_options.md>`_.
+
+.. note::
+  You can use ``cyan init`` to set up a directory for a Teal project automatically.
+
+In addition to setting up a build process, you will need the `declaration files for the OpenMW API <https://gitlab.com/OpenMW/openmw/-/jobs/artifacts/master/raw/teal_declarations.zip?job=Teal>`_.
+Unpack them into a directory of your choice, and add that path to the ``include_dir`` option in your ``tlconfig.lua``. Alternatively, you can add ``-I <my-dcelaration-directory-path>`` as an agument to ``Cyan`` commands.
+
+After everything is ready, run ``cyan build`` in the same directory as ``tlconfig.lua``. It will find all the ``.tl`` files in the ``source_dir``, and put compiled ``.lua`` files at the same relative paths inside ``build_dir``.
+Running ``cyan build`` will also perform a type check, notifying you of any mismatches or mistakes.
+
+.. note::
+  ``source_dir`` and ``build_dir`` can be the same directory. In fact, that is the recommended arrangement, so that it's convenient to include the original sources with your scripts.
+
+IDE support
+===========
+
+Work on `Teal Language Server <https://github.com/teal-language/teal-language-server>`_ is still ongoing, so for now the only supported IDE is `Visual Studio Code <https://code.visualstudio.com/>`_.
+It's available on Windows, Linux and Mac, so most likely you can run it too.
+Teal's extension can be found here: `VSCode Marketplace <https://marketplace.visualstudio.com/items?itemName=pdesaulniers.vscode-teal>`_ (or simply search for "Teal" in the extension UI).
+
+.. note::
+  VSCode also has a web version, but the Teal extension isn't available there.

docs/tlconfig.lua

@@ -0,0 +1,6 @@
+-- used for checking generated declarations
+return {
+  gen_target = '5.1',
+  gen_compat = 'off',
+  include_dir = { '.', },
+}

scripts/generate_teal_declarations.sh

@@ -0,0 +1,48 @@
+if [ -z "$LUAROCKS" ]; then
+  echo "Requires the LUAROCKS variable to be set to the luarocks/bin directory, e. g. `~/.luarocks/bin`"
+  exit
+fi
+
+if [ -z "$1" ]; then
+  echo "Takes a path to the output directory as the argument"
+  exit
+fi
+
+SCRIPTS_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+OPENMW_DIR=$(realpath $SCRIPTS_DIR/..)
+DOCS_DIR=$(realpath $OPENMW_DIR/docs)
+FILES_DIR=$(realpath $OPENMW_DIR/files)
+OUTPUT_DIR=$(realpath "$1")
+DOCUMENTOR_PATH=$LUAROCKS/openmwluadocumentor
+TEAL_PATH=$LUAROCKS/cyan
+
+rm -rf $OUTPUT_DIR
+mkdir $OUTPUT_DIR
+cp "$DOCS_DIR/tlconfig.lua" "$OUTPUT_DIR/tlconfig.lua"
+
+build_path() {
+  for file in $1
+  do
+    mkdir -p $OUTPUT_DIR/$(dirname $file)
+    $DOCUMENTOR_PATH -f teal -d "$OUTPUT_DIR" $file
+  done
+}
+
+cd $FILES_DIR
+build_path "lua_api/openmw/*lua"
+
+data_paths=$($DOCS_DIR/source/luadoc_data_paths.sh)
+for path in $data_paths
+do
+  build_path "data/$path"
+done
+
+cd $OUTPUT_DIR
+
+mv lua_api/openmw ./
+rm -r lua_api
+
+mv data/* ./
+rm -r data
+
+"$TEAL_PATH" check **/*.d.tl