From 072ec79b51cb4af45b168bf6f73941d1de94c8ae Mon Sep 17 00:00:00 2001 From: Charles Cabergs Date: Sun, 28 Feb 2021 20:41:21 +0100 Subject: Added full config documentation, Splitting original README in multiple doc pages --- docs/config.rst | 139 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 70 insertions(+), 69 deletions(-) (limited to 'docs/config.rst') diff --git a/docs/config.rst b/docs/config.rst index 884cf9b..f35251d 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -3,139 +3,140 @@ Configuration ============= -Configuration file ------------------- +File +---- -It looks for a ``minishell_test.cfg`` file in your project directory. +The configuration file is named ``minishell_test.cfg`` and should be located at the root of your project. Here is what the default configuration looks like: .. include:: ../minishell_test/data/default.cfg - :code: cfg + :code: ini -The format of this file is described in more details `here `_ +The format of this file is described in more details +`here `_. Global ------ -Global settings are defined under the ``minishell_test`` section: - -.. code-block:: cfg - - [minishell_test] - bonus = true +Global settings are defined under the ``[minishell_test]`` section. .. conf:: bonus :type: true|false - :default: false - Run the bonus tests + Enable the bonus tests (:ref:`bonus`). -.. conf:: exec_name +.. conf:: make - :type: PATH - :default: minishell + :type: true|false - Minishell executable name + Run the ``make`` command in your project directory before the test. -.. conf:: make +.. conf:: make_args - :type: true|false - :default: true + :type: space separated list - Run ``make`` in your project directory before the test + | Argument given to the ``make`` command. + | The default value (``MINISHELL_TEST_FLAGS=-DMINISHELL_TEST``) allows you to do conditional compilation + to support both the ``-c`` option and the :ref:`subject` + (which doesn't say anything about options, so we assumed the minishell executable didn't take any). -.. conf:: pager + | In your ``Makefile`` add ``$(MINISHELL_TEST_FLAGS)`` in your object compilation command. + (e.g ``$(CC) $(CCFLAGS) -c -o $@ $<``) - :type: NAME - :default: less + | You can then have something resembling the following in your ``main``: - Pager to use when viewing your results + .. code:: c -.. conf:: log_path + #ifndef MINISHELL_TEST + int main(int argc, char **argv) + { + if (argc != 1) error; + ... + } + #else + int main(int argc, char **argv) + { + if (argc != 3 && strcmp(argv[1], "-c") == 0) do the thing; + ... + } + #endif - :type: PATH - :default: minishell_test.log +.. conf:: check_error_messages - File where to put the test results + :type: true|false -.. conf:: cache_path + | If is ``true``, will ignore the content of the error messages outputted by the reference shell, + | Useful if you have implemented your own error messages and don't want to copy bash's ones. + +.. conf:: pager - :type: PATH - :default: $XDG_CACHE_HOME/minishell_test ^ ~/.cache/minishell_test + :type: command name + | Pager to use when viewing your results after the tests finished running. + | Will be called like so: ``{pager} {log_filename}``. Shell ----- -Shell settings are defined under the ``shell`` section: - -.. code-block:: cfg - - [shell] - available_commands = ls,cat +Shell settings are defined under the ``[shell]`` section. .. conf:: available_commands - :type: LIST - :default: rmdir env cat touch ls grep sh head + :type: multi-line list + + Commands available in a test. - Commands available in test + .. warning:: + Some of the default tests won't serve their purpose + if the default available commands are not present. .. conf:: path_variable - :type: LIST - :default: {cache:executables_path} + :type: string (``:`` separated directories) - ``$PATH`` environment variable passed to the shell + ``$PATH`` environment variable passed to the shell. + + .. note:: + ``{shell_available_commands_dir}`` will be replaced by the directory + where the available commands are stored. Reference +++++++++ -Reference shell settings are defined under the ``shell:reference`` section: - -.. code-block:: cfg - - [shell:reference] - path = /bin/sh +Reference shell settings are defined under the ``[shell:reference]`` section. .. conf:: path - :type: PATH - :default: /bin/bash + :type: path + + Path to reference shell, the one to which minishell will be compared. - Path to reference shell (shell which will be compared minishell) - has to support the ``-c`` option (``sh``, ``bash`` and ``zsh`` support it) + .. note:: + has to support the ``-c`` option, ``sh``, ``bash`` and ``zsh`` support it. .. conf:: args - :type: ARGV + :type: space separated list - | Supplementary arguments to the reference shell - | e.g ``--posix`` can be used with bash for a more posix complient behavior + | Supplementary arguments to the reference shell. + | e.g ``--posix`` can be used with bash for a more posix compliant behavior. Timeout ------- -Timeout settings are defined under the ``timeout`` section: - -.. code-block:: cfg - - [timeout] - leaks = 60 +Timeout settings are defined under the ``[timeout]`` section. .. conf:: test - :type: FLOAT - :default: 0.5 + :type: float (seconds) - Time before a timeout occurs on a regular test (in seconds) + Time before a timeout occurs on a regular test. .. conf:: leaks - :type: FLOAT - :default: 10 + :type: float (seconds) - Time before a timeout occurs on a leak test (with valgrind) (in seconds) + Time before a timeout occurs on a leak test (with ``valgrind``). -- cgit