From 0979fd0ab727f838a1d30691c7c697121fbc957a Mon Sep 17 00:00:00 2001 From: raiden00pl Date: Tue, 24 Oct 2023 12:22:36 +0200 Subject: [PATCH] Documentaion: migrate interpreters/readme --- .../applications/interpreters/bas/index.rst | 64 +++++++++++++++++++ .../applications/interpreters/ficl/index.rst | 44 +++++++++++++ .../applications/interpreters/index.rst | 14 ++-- .../applications/interpreters/lua/index.rst | 17 +++++ .../interpreters/minibasic/index.rst | 11 ++++ 5 files changed, 146 insertions(+), 4 deletions(-) create mode 100644 Documentation/applications/interpreters/bas/index.rst create mode 100644 Documentation/applications/interpreters/ficl/index.rst create mode 100644 Documentation/applications/interpreters/lua/index.rst create mode 100644 Documentation/applications/interpreters/minibasic/index.rst diff --git a/Documentation/applications/interpreters/bas/index.rst b/Documentation/applications/interpreters/bas/index.rst new file mode 100644 index 0000000000..4ae28961aa --- /dev/null +++ b/Documentation/applications/interpreters/bas/index.rst @@ -0,0 +1,64 @@ +============================= +``bas`` Bas BASIC Interpreter +============================= + +Introduction +------------ + +Bas is an interpreter for the classic dialect of the programming language BASIC. +It is pretty compatible to typical BASIC interpreters of the 1980s, unlike some +other UNIX BASIC interpreters, that implement a different syntax, breaking +compatibility to existing programs. Bas offers many ANSI BASIC statements for +structured programming, such as procedures, local variables and various loop +types. Further there are matrix operations, automatic LIST indentation and many +statements and functions found in specific classic dialects. Line numbers are +not required. + +The interpreter tokenises the source and resolves references to variables and +jump targets before running the program. This compilation pass increases +efficiency and catches syntax errors, type errors and references to variables +that are never initialised. Bas is written in ANSI C for UNIX systems. + +License +------- + +BAS 2.4 is released as part of NuttX under the standard 3-clause BSD license use +by all components of NuttX. This is not incompatible with the original BAS 2.4 +licensing + +Copyright (c) 1999-2014 Michael Haardt + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +Bas 2.4 Release Notes +--------------------- + +Changes compared to version ``2.3`` + +- Matrix inversion on integer arrays with option base 1 fixed. +- ``PRINT USING`` behaviour for ``!`` fixed. +- ``PRINT``, separator should advance to the next zone, even if the current + position is at the start of a zone. +- Added ``ip()``, ``frac()``, ``fp()``, ``log10()``, ``log2()``, ``min()`` and ``max()``. +- Fixed ``NEXT`` checking the variable case sensitive. +- Use ``terminfo`` capability cr to make use of its padding. +- ``LET`` segmentation fault fixed. +- ``PRINT`` now uses print items. +- ``-r`` for restricted operation. +- ``MAT INPUT`` does not drop excess arguments, but uses them for the next row. +- License changed to MIT. diff --git a/Documentation/applications/interpreters/ficl/index.rst b/Documentation/applications/interpreters/ficl/index.rst new file mode 100644 index 0000000000..1f9c8c2e43 --- /dev/null +++ b/Documentation/applications/interpreters/ficl/index.rst @@ -0,0 +1,44 @@ +=============================== +``ficl`` Ficl Forth interpreter +=============================== + +Ficl is a programming language interpreter designed to be embedded into other +systems as a command, macro, and development prototyping language. + +This is DIY port of Ficl (the "Forth Inspired Command Language"). See +http://ficl.sourceforge.net/. It is a "" port because the Ficl source is not +in that directory, only an environment and instructions that will let you build +Ficl under NuttX. The rest is up to you. + +Build Instructions +------------------ + +Disclaimer: This installation steps have only been exercised using Ficl 4.1.0. +With new versions you will likely have to make some adjustments to this +instructtions or to the files within this directory. Think of this information +as _recommendations_ - not necessarily proven instructions. + +1. ``cd`` to ``interpreters/ficl`` + +2. Download Ficl: http://sourceforge.net/projects/ficl/files/ + +3. Uznip the Ficl compressed file. + + For example, ``unzip ficl-4.1.0.zip`` will leave the file + ``interpreters/ficl/ficl-4.1.0``. + +4. Configure to build Ficl in the ``interpreters/ficl`` directory using the + ``configure.sh`` script. + + For example, ``./configure.sh ficl-4.1.0`` will leave the Makefile fragment + ``Make.srcs`` in the ficl build directory. + +5. Create your NuttX configuration. Using the ``make menuconfig``, you should + select:: + + CONFIG_INTERPRETERS_FICL=y + +6. Configure and build NuttX. On successful completion, the Ficl objects will be + available in ``apps/libapps.a`` and that NuttX binary will be linked against + that file. Of course, Ficl will do nothing unless you have written some + application code that uses it! diff --git a/Documentation/applications/interpreters/index.rst b/Documentation/applications/interpreters/index.rst index c1debdfd64..ec0a879c09 100644 --- a/Documentation/applications/interpreters/index.rst +++ b/Documentation/applications/interpreters/index.rst @@ -2,13 +2,19 @@ Interpreters ============ -- bas - Basic Interpreter +This `apps/` directory is set aside to hold interpreters that may be +incorporated into NuttX. + +.. toctree:: + :glob: + :maxdepth: 3 + :titlesonly: + + */* + - duktape - Duktape JavaScript interpreter -- ficl - Ficl Forth interpreter -- lua - Lua interpreter - luajit - LuaJIT interpreter - luamodules: cjson, lfs, luasyslog, luv -- minibasic - Mini Basic Interpreter - quickjs - QuickJS JavaScript interpreter - toywasm - Toywasm Webassembly Runtime - wamr - Webassembly Micro Runtime diff --git a/Documentation/applications/interpreters/lua/index.rst b/Documentation/applications/interpreters/lua/index.rst new file mode 100644 index 0000000000..1b088df1e1 --- /dev/null +++ b/Documentation/applications/interpreters/lua/index.rst @@ -0,0 +1,17 @@ +======================= +``lua`` Lua interpreter +======================= + +Fetch and build a Lua interpreter. Versions 5.2 through 5.4 are supported. The +``lua`` command will be added to NSH. Lua can run a script for a given path, +execute a string of code, or open a readline compatible REPL on the NSH console. +The ```` and ```` headers are available to start a new embedded +interpreter or extend Lua with C modules. See the ``luamod_hello`` example for how +to include a built-in module. + +A math library is required to build. Enable the ``LIBM`` config or use a +toolchain provided math library. + +The following configs are recommended for a full featured Lua interpreter: +- ``LIBC_FLOATINGPOINT`` +- ``SYSTEM_READLINE`` diff --git a/Documentation/applications/interpreters/minibasic/index.rst b/Documentation/applications/interpreters/minibasic/index.rst new file mode 100644 index 0000000000..52d334313d --- /dev/null +++ b/Documentation/applications/interpreters/minibasic/index.rst @@ -0,0 +1,11 @@ +==================================== +``minibasic`` Mini Basic Interpreter +==================================== + +The Mini Basic implementation at ``apps/interpreters`` derives from version ``1.0`` +by Malcolm McLean, Leeds University, and was released under the Creative Commons +Attibution license. I am not legal expert, but this license appears to be +compatible with the NuttX BSD license see: +https://creativecommons.org/licenses/. I, however, cannot take responsibility +for any actions that you might take based on my understanding. Please use your +own legal judgement.