Merge pull request #19 from ngie-eign/doc-updates

lutok: documentation updates in preparation for the 0.5 release

INSTALL.md

@@ -1,4 +1,4 @@
-# Installation instructions
+# Introduction
 
 Lutok uses the GNU Automake, GNU Autoconf and GNU Libtool utilities as
 its build system.  These are used only when compiling the library from
@@ -7,30 +7,33 @@ package, you do not need to read this document.
 
 For the impatient:
 
+    ```shell
     $ ./configure
     $ make
     $ make check
     Gain root privileges
     # make install
     Drop root privileges
     $ make installcheck
+    ```
 
 Or alternatively, install as a regular user into your home directory:
 
+    ```shell
     $ ./configure --prefix ~/local
     $ make
     $ make check
     $ make install
     $ make installcheck
+    ```
 
-
-## Dependencies
+# Dependencies
 
 To build and use Lutok successfully you need:
 
-* A standards-compliant C++ complier.
+* A C++-11 standards-compliant compiler.
 * Lua 5.1 or greater.
-* pkgconf or pkg-config.
+* pkg-config or an equivalent tool, e.g., pkgconf.
 
 Optionally, if you want to build and run the tests (recommended), you
 need:
@@ -41,134 +44,141 @@ need:
 If you are building Lutok from the code on the repository, you will also
 need the following tools:
 
-* GNU Autoconf.
-* GNU Automake.
+* GNU Autoconf 2.68 (or later).
+* GNU Automake 1.9 (or later).
 * GNU Libtool.
 
 
-## Regenerating the build system
+# Regenerating the build system
 
 This is not necessary if you are building from a formal release
 distribution file.
 
 On the other hand, if you are building Lutok from code extracted from
 the repository, you must first regenerate the files used by the build
 system.  You will also need to do this if you modify `configure.ac`,
-`Makefile.am` or any of the other build system files.  To do this, simply
+`Makefile.am`, or any of the other build system files.  To do this, simply
 run:
 
+    ```shell
     $ autoreconf -i -s
+    ```
 
-If ATF is installed in a different prefix than Autoconf, you will also
-need to tell autoreconf where the `ATF M4` macros are located.  Otherwise,
-the configure script will be incomplete and will show confusing syntax
+If ATF is installed in a different prefix than `autoconf`, you will also
+need to tell `autoreconf` where the ATF m4 macros are located.  Otherwise,
+the `configure` script will be incomplete and will show confusing syntax
 errors mentioning, for example, `ATF_CHECK_SH`.  To fix this, you have
-to run autoreconf in the following manner, replacing `<atf-prefix>` with
+to run `autoreconf` in the following manner, replacing `<atf-prefix>` with
 the appropriate path:
 
+    ```shell
     $ autoreconf -i -s -I <atf-prefix>/share/aclocal
+    ```
 
-
-## General build procedure
+# General build procedure
 
 To build and install the source package, you must follow these steps:
 
-1. Configure the sources to adapt to your operating system.  This is
+#. Configure the sources to adapt to your operating system.  This is
    done using the `configure` script located on the sources' top
    directory, and it is usually invoked without arguments unless you
    want to change the installation prefix.  More details on this
    procedure are given on a later section.
 
-2. Build the sources to generate the binaries and scripts.  Simply run
+#. Build the sources to generate the binaries and scripts.  Simply run
    `make` on the sources' top directory after configuring them.  No
    problems should arise.
 
-3. Install the library by running `make install`.  You may need to
+#. Install the library by running `make install`.  You may need to
    become root to issue this step.
 
-4. Issue any manual installation steps that may be required.  These are
+#. Issue any manual installation steps that may be required.  These are
    described later in their own section.
 
-5. Check that the installed library works by running `make
-   installcheck`.  You do not need to be root to do this.
+#. Check that the installed library works by running `make installcheck`.
+   You do not need to be root to do this.
 
 
-## Configuration flags
+# Configuration flags
 
 The most common, standard flags given to `configure` are:
 
-* `--prefix=directory`:
-  **Possible values:** Any path
-  **Default:** `/usr/local`
+## `--prefix=directory`
+    - **Possible values**: any path
+    - **Default**: "/usr/local"
 
-  Specifies where the library (binaries and all associated files) will
-  be installed.
+      Specifies where the library (binaries and all associated files) will
+      be installed.
 
-* `--help`:
-  Shows information about all available flags and exits immediately,
-  without running any configuration tasks.
+## `--help`
+      Shows information about all available flags and exits immediately,
+      without running any configuration tasks.
 
 The following flags are specific to Lutok's `configure` script:
 
-* `--enable-developer`:
-  **Possible values:** `yes`, `no`
-  **Default:** `yes` in HEAD builds; `no` in release builds.
+- `--enable-developer`
+    - **Possible values**: "yes", "no"
+    - **Default**: "yes" in Git HEAD builds; "no" in formal releases.
 
-  Enables several features useful for development, such as the inclusion
-  of debugging symbols in all objects or the enforcement of compilation
-  warnings.
+      Enables several features useful for development, such as the inclusion
+      of debugging symbols in all objects or the enforcement of compilation
+      warnings.
 
-  The compiler will be executed with an exhaustive collection of warning
-  detection features regardless of the value of this flag.  However, such
-  warnings are only fatal when `--enable-developer` is `yes`.
+      The compiler will be executed with an exhaustive collection of warning
+      detection features regardless of the value of this flag.  However, such
+      warnings are only fatal when `--enable-developer` is set to "yes".
 
-* `--with-atf`:
-  **Possible values:** `yes`, `no`, `auto`.
-  **Default:** `auto`.
+- `--with-atf`
+    - **Possible values**: "yes", "no", "auto".
+    - **Default**: "auto"
 
-  Enables usage of ATF to build (and later install) the tests.
+      Enables usage of ATF to build (and later install) the tests.
 
-  Setting this to `yes` causes the configure script to look for ATF
-  unconditionally and abort if not found.  Setting this to `auto` lets
-  configure perform the best decision based on availability of ATF.
-  Setting this to `no` explicitly disables ATF usage.
+      Setting this to "yes" causes the `configure` script to look for ATF
+      unconditionally and abort if not found.  Setting this to "auto" lets
+      `configure` perform the best decision based on availability of ATF.
+      Setting this to "no" explicitly disables ATF usage.
 
-  When support for tests is enabled, the build process will generate the
-  test programs and will later install them into the tests tree.
-  Running `make check` or `make installcheck` from within the source
-  directory will cause these tests to be run with Kyua (assuming it is
-  also installed).
+      When support for tests is enabled, the build process will generate the
+      test programs and will later install them into the tests tree.
+      Running `make check` or `make installcheck` from within the source
+      directory will cause these tests to be run with Kyua (assuming it is
+      also installed).
 
-* `--with-doxygen`:
-  **Possible values:** `yes`, `no`, `auto` or a path.
-  **Default:** `auto`.
+- `--with-doxygen`
+    - **Possible values**: "yes", "no", "auto", or a path.
+    - **Default**: "auto".
 
-  Enables usage of Doxygen to generate documentation for internal APIs.
+      Enables usage of Doxygen to generate documentation for internal APIs.
 
-  Setting this to `yes` causes the configure script to look for Doxygen
-  unconditionally and abort if not found.  Setting this to `auto` lets
-  configure perform the best decision based on availability of Doxygen.
-  Setting this to `no` explicitly disables Doxygen usage.  And, lastly,
-  setting this to a path forces configure to use a specific Doxygen
-  binary, which must exist.
+      Setting this to "yes" causes the `configure` script to look for Doxygen
+      unconditionally and abort if not found.  Setting this to "auto" lets
+      `configure` perform the best decision based on availability of Doxygen.
+      Setting this to "no" explicitly disables Doxygen usage.  And, lastly,
+      setting this to a path forces `configure` to use a specific Doxygen
+      binary, which must exist.
 
-  When support for Doxygen is enabled, the build process will generate
-  HTML documentation for the Lutok API.  This documentation will later
-  be installed in the HTML directory specified by the configure script.
-  You can change the location of the HTML documents by providing your
-  desired override with the `--htmldir` flag to the configure script.
+      When support for Doxygen is enabled, the build process will generate
+      HTML documentation for the Lutok API.  This documentation will later
+      be installed in the HTML directory specified by the `configure` script.
+      You can change the location of the HTML documents by providing your
+      desired override with the `--htmldir` flag to the `configure` script.
 
 
-## Run the tests!
+Run the tests!
+==============
 
 Lastly, after a successful installation (and assuming you built the
 sources with support for ATF), you should periodically run the tests
 from the final location to ensure things remain stable.  Do so as
 follows:
 
+    ```shell
     $ kyua test -k /usr/local/tests/lutok/Kyuafile
+    ```
+
+And if you see any tests fail, do not hesitate to report them in:
 
-And if you see any tests fail, do not hesitate to report them on
-[GitHub issues](https://github.com/freebsd/lutok/issues/)
+    https://github.com/freebsd/lutok/issues/
 
 Thank you!

NEWS.md

@@ -1,5 +1,17 @@
 # Major changes between releases
 
+## Changes in version 0.5 (UNRELEASED)
+
+Released on 2024/05/XX.
+
+* Use more modern autotools macros.  Bump the minimum autoconf version to 2.68 to
+  support this change.
+
+* Modify build code to improve Lua 5.4 support.
+
+* Replace `std::auto_ptr` use with `std::unique_ptr` use.  This improves C++
+  standard support and fixes the build with newer C++ standards.
+
 ## Changes in version 0.4
 
 Released on 2013/12/07.
@@ -8,21 +20,21 @@ Released on 2013/12/07.
   appeared in Automake 1.11.2.  Fixes a problem in Ubuntu 10.04
   LTS, which appears stuck in 1.11.1.
 
-* Stopped shipping an Atffile.  The only supported way to run the tests
+* Stopped shipping an `Atffile`.  The only supported way to run the tests
   is via Kyua.
 
 Interface changes:
 
-* Issue 5: New methods added to the state class: open_all.
+* Issue 5: New methods added to the state class: `open_all`.
 
 * Removed default parameter values from all state methods and all
   standalone operations.  It is often unclear what the default value is
   given that it depends on the specific Lua operation.  Being explicit
   on the caller side is clearer.
 
-* Modified operations do_file and do_string to support passing a number
+* Modified operations `do_file` and `do_string` to support passing a number
   of arguments to the loaded chunks and an error handler to the backing
-  pcall call.
+  `pcall` call.
 
 
 ## Changes in version 0.3
@@ -40,21 +52,21 @@ Released on 2013/06/14.
 
 Interface changes:
 
-* New global constants: registry_index.
+* New global constants: `registry_index`.
 
-* New methods added to the state class: get_global_table.
+* New methods added to the state class: `get_global_table`.
 
-* Removed global constants: globals_index.
+* Removed global constants: `globals_index`.
 
 
 ## Changes in version 0.2
 
 Released on 2012/05/30.
 
-* New global constants: globals_index.
+* New global constants: `globals_index`.
 
-* New methods added to the state class: get_metafield, get_metatable,
-  insert, push_value, raw_get and raw_set.
+* New methods added to the state class: `get_metafield`, `get_metatable`,
+  `insert`, `push_value`, `raw_get`, and `raw_set`.
 
 * Acknowledged that Lua 5.2 is currently not supported.
 

configure.ac

@@ -26,7 +26,7 @@ dnl THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 dnl (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 dnl OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-AC_INIT([Lutok], [0.4],
+AC_INIT([Lutok], [0.5],
         [testing@FreeBSD.org], [lutok],
         [https://github.com/freebsd/lutok/])
 AC_PREREQ([2.68])