From 95849edbba68dd453f6d9f9167ad18ceafdb4b40 Mon Sep 17 00:00:00 2001 From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com> Date: Tue, 23 Jan 2024 17:35:06 +1300 Subject: [PATCH] Docs: changes from JF `yosys-witness` prereq `click`. Yosys environment vars & `yosys --help` output. Removing Ubuntu/macOS version numbers/names. Hide `troubleshooting` page. --- Makefile | 2 +- docs/source/appendix/auxprogs.rst | 4 +++ docs/source/appendix/env_vars.rst | 31 +++++++++++++++++++ docs/source/cmd_ref.rst | 5 +++ docs/source/test_suites.rst | 15 ++++++--- .../using_yosys/more_scripting/index.rst | 3 +- .../more_scripting/troubleshooting.rst | 2 +- 7 files changed, 54 insertions(+), 8 deletions(-) create mode 100644 docs/source/appendix/env_vars.rst diff --git a/Makefile b/Makefile index cf73728ea..753ff9b92 100644 --- a/Makefile +++ b/Makefile @@ -982,7 +982,7 @@ docs/guidelines: # many of these will return an error which can be safely ignored, so we prefix # the command with a '-' -DOCS_USAGE_PROGS := yosys-config yosys-filterlib yosys-abc yosys-smtbmc yosys-witness +DOCS_USAGE_PROGS := yosys yosys-config yosys-filterlib yosys-abc yosys-smtbmc yosys-witness docs/usage: $(addprefix docs/source/temp/,$(DOCS_USAGE_PROGS)) docs/source/temp/%: docs/guidelines -$(Q) ./$(PROGRAM_PREFIX)$* --help > $@ 2>&1 diff --git a/docs/source/appendix/auxprogs.rst b/docs/source/appendix/auxprogs.rst index 752d4a0c8..b6defbe80 100644 --- a/docs/source/appendix/auxprogs.rst +++ b/docs/source/appendix/auxprogs.rst @@ -57,3 +57,7 @@ independent of the solver. .. literalinclude:: /temp/yosys-witness :start-at: Usage + +.. note:: ``yosys-witness`` requires `click`_ Python package for use. + +.. _click: https://pypi.org/project/click/ diff --git a/docs/source/appendix/env_vars.rst b/docs/source/appendix/env_vars.rst new file mode 100644 index 000000000..bb8ef34df --- /dev/null +++ b/docs/source/appendix/env_vars.rst @@ -0,0 +1,31 @@ +Yosys environment variables +=========================== + +``HOME`` + Yosys command history is stored in ``$HOME/.yosys_history``. Graphics (from + :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this directory by + default. This environment variable is also used in some cases for resolving + filenames with ``~``. + +``PATH`` + May be used in OpenBSD builds for finding the location of Yosys executable. + +``TMPDIR`` + Used for storing temporary files. + +``ABC`` + When compiling Yosys with out-of-tree ABC using ``ABCEXTERNAL``, this + variable can be used to override the external ABC executable. + +``YOSYS_NOVERIFIC`` + If Yosys was built with Verific, this environment variable can be used to + temporarily disable Verific support. + +``YOSYS_COVER_DIR`` and ``YOSYS_COVER_FILE`` + When using code coverage, these environment variables control the output file + name/location. + +``YOSYS_ABORT_ON_LOG_ERROR`` + Can be used for debugging Yosys internals. Setting it to 1 causes abort() to + be called when Yosys terminates with an error message. + diff --git a/docs/source/cmd_ref.rst b/docs/source/cmd_ref.rst index 24b24015a..f0c4eaaf9 100644 --- a/docs/source/cmd_ref.rst +++ b/docs/source/cmd_ref.rst @@ -3,9 +3,14 @@ ================================================================================ Command line reference ================================================================================ + +.. literalinclude:: /temp/yosys + :start-at: Usage + .. toctree:: :caption: Command reference :maxdepth: 1 :glob: + /appendix/env_vars /cmd/* diff --git a/docs/source/test_suites.rst b/docs/source/test_suites.rst index 3e016400e..2edb0e67d 100644 --- a/docs/source/test_suites.rst +++ b/docs/source/test_suites.rst @@ -6,15 +6,20 @@ Testing Yosys Automatic testing ----------------- -The `Yosys Git repo`_ has automatic testing of builds and running of the -included test suite on the following platforms: - .. only:: html - - Ubuntu 20.04 (Focal Fossa) |test-linux| - - macOS 11 (Big Sur) |test-macos| + The `Yosys Git repo`_ has automatic testing of builds and running of the + included test suite on the following platforms: + + - Ubuntu |test-linux| + - macOS |test-macos| .. _Yosys Git repo: https://github.com/YosysHQ/yosys .. |test-linux| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-linux.yml/badge.svg?branch=master .. |test-macos| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-macos.yml/badge.svg?branch=master + +For up to date information, including OS versions, refer to `the git actions +page`_. + +.. _the git actions page: https://github.com/YosysHQ/yosys/actions diff --git a/docs/source/using_yosys/more_scripting/index.rst b/docs/source/using_yosys/more_scripting/index.rst index 7c3f2ae56..2d67b6a09 100644 --- a/docs/source/using_yosys/more_scripting/index.rst +++ b/docs/source/using_yosys/more_scripting/index.rst @@ -9,4 +9,5 @@ More scripting load_design selections interactive_investigation - troubleshooting + +.. troubleshooting diff --git a/docs/source/using_yosys/more_scripting/troubleshooting.rst b/docs/source/using_yosys/more_scripting/troubleshooting.rst index 8b7876607..a17a552d2 100644 --- a/docs/source/using_yosys/more_scripting/troubleshooting.rst +++ b/docs/source/using_yosys/more_scripting/troubleshooting.rst @@ -1,6 +1,6 @@ Troubleshooting ~~~~~~~~~~~~~~~ -.. TODO:: more on troubleshooting +.. todo:: troubleshooting document(?) See :doc:`/cmd/bugpoint`