diff --git a/.clang-format b/.clang-format index 251eebe52..b41d0c25a 100644 --- a/.clang-format +++ b/.clang-format @@ -17,7 +17,7 @@ AllowShortLoopsOnASingleLine: true AlwaysBreakAfterDefinitionReturnType: None AlwaysBreakAfterReturnType: None AlwaysBreakBeforeMultilineStrings: false -AlwaysBreakTemplateDeclarations: false +AlwaysBreakTemplateDeclarations: true BinPackArguments: true BinPackParameters: true BraceWrapping: @@ -59,15 +59,27 @@ ForEachMacros: - foreach - Q_FOREACH - BOOST_FOREACH -IncludeBlocks: Preserve + +# Include grouping/sorting +SortIncludes: true +IncludeBlocks: Regroup IncludeCategories: - - Regex: '^"(llvm|llvm-c|clang|clang-c)/' - Priority: 2 - - Regex: '^(<|"(gtest|gmock|isl|json)/)' - Priority: 3 - - Regex: '.*' - Priority: 1 -IncludeIsMainRegex: '(Test)?$' + - Regex: '"(config_build|verilated_config|verilatedos)\.h"' + Priority: -1 # Sepecials before main header + - Regex: '(<|")verilated.*' + Priority: 1 # Runtime headers + - Regex: '"V3.*__gen.*\.h"' + Priority: 3 # Generated internal headers separately + - Regex: '"V3.*"' + Priority: 2 # Internal header + - Regex: '".*"' + Priority: 4 # Other non-system headers + - Regex: '<[[:alnum:]_.]+>' + Priority: 5 # Simple system headers next + - Regex: '<.*>' + Priority: 6 # Other system headers next +IncludeIsMainRegex: '$' + IndentCaseLabels: false IndentPPDirectives: None IndentWidth: 4 @@ -91,7 +103,6 @@ PenaltyExcessCharacter: 1000000 PenaltyReturnTypeOnItsOwnLine: 60 PointerAlignment: Left ReflowComments: true -SortIncludes: false SortUsingDeclarations: true SpaceAfterCStyleCast: false SpaceAfterTemplateKeyword: true diff --git a/Changes b/Changes index 984897289..98f97de74 100644 --- a/Changes +++ b/Changes @@ -8,6 +8,39 @@ The changes in each Verilator version are described below. The contributors that suggested a given feature are shown in []. Thanks! +Verilator 4.226 2022-08-31 +========================== + +**Minor:** + +* Add --future0 and --future1 options. +* Support class parameters (#2231) (#3541). [Arkadiusz Kozdra/Antmicro] +* Support wildcard index associative arrays (#3501). [Arkadiusz Kozdra/Antmicro] +* Support negated properties (#3572). [Aleksander Kiryk] +* Support $test$plusargs(expr) (#3489). +* Rename trace rolloverSize() (#3570). +* Improve Verilation speed with --threads on large designs. [Geza Lore] +* Fix struct pattern assignment (#2328) (#3517). [Mostafa Gamal] +* Fix public combo propagation issues (#2905). [Todd Strader] +* Fix incorrect tristate logic (#3399) [shareefj, Vighnesh Iyer] +* Fix incorrect bit op tree optimization (#3470). [algrobman] +* Fix bisonpre for MSYS2 (#3471). +* Fix max memory usage (#3483). [Kamil Rakoczy] +* Fix empty string arguments to display (#3484). [Grulfen] +* Fix table misoptimizing away display (#3488). [Stefan Post] +* Fix unique_ptr memory header for MinGW64 (#3493). +* Fix $dump systemtask with --output-split-cfuncs (#3495) (#3497). [Varun Koyyalagunta] +* Fix wrong bit op tree optimization (#3509). [Nathan Graybeal] +* Fix nested default assignment for struct pattern (#3511) (#3524). [Mostafa Gamal] +* Fix sformat string incorrectly cleared (#3515) (#3519). [Gustav Svensk] +* Fix segfault exporting non-existant package (#3535). +* Fix void-cast queue pop_front or pop_back (#3542) (#3364). [Drew Ranck] +* Fix case statement comparing string literal (#3544). [Gustav Svensk] +* Fix === with some tristate constants (#3551). [Ryszard Rozak] +* Fix converting subclasses to string (#3552). [Arkadiusz Kozdra/Antmicro] +* Fix --hierarchical with order-based pin connections (#3583) (#3585). [Kelin9298] + + Verilator 4.224 2022-06-19 ========================== @@ -26,7 +59,7 @@ Verilator 4.224 2022-06-19 * Improve conditional merging optimization (#3125). [Geza Lore, Shunyao CAD] * Define VM_TRACE_VCD when tracing in VCD format. [Geza Lore, Shunyao CAD] * Add assert when VerilatedContext is mis-deleted (#3121). [Rupert Swarbrick] -* Internal prep work towards timing control. [Krzysztof Bieganski] +* Internal prep work towards timing control. [Krzysztof Bieganski/Antmicro] * Fix hang with large case statement optimization (#3405). [Mike Urbach] * Fix UNOPTFLAT warning from initial static var (#3406). [Kamil Rakoczy] * Fix compile error when enable VL_LEAK_CHECKS (#3411). [HungMingWu] @@ -193,7 +226,7 @@ Verilator 4.212 2021-09-01 * Fix re-evaluation of logic dependent on state set in DPI exports (#3091). [Geza Lore] * Support unpacked array localparams in tasks/functions (#3078). [Geza Lore] * Support timeunit/timeprecision in $unit. -* Support assignment patterns as children of pins (#3041). [Krzysztof Bieganski] +* Support assignment patterns as children of pins (#3041). [Krzysztof Bieganski/Antmicro] * Add --instr-count-dpi to tune assumed DPI import cost for multithreaded model scheduling. Default value changed to 200 (#3068). [Yinan Xu] * Output files are split based on the set of headers required @@ -258,7 +291,7 @@ Verilator 4.204 2021-06-12 * Prep work towards better ccache hashing/performance. [Geza Lore] * Fix assertion failure in bitOpTree optimization (#2891) (#2899). [Raynard Qiao] * Fix DPI functions not seen as vpiModule (#2893). [Todd Strader] -* Fix bounds check in VL_SEL_IWII (#2910). [Krzysztof Bieganski] +* Fix bounds check in VL_SEL_IWII (#2910). [Krzysztof Bieganski/Antmicro] * Fix slowdown in elaboration (#2911). [Nathan Graybeal] * Fix initialization of assoc in assoc array (#2914). [myftptoyman] * Fix make support for gmake 3.x (#2920) (#2921). [Philipp Wagner] @@ -373,7 +406,7 @@ Verilator 4.108 2021-01-10 **Major:** * Many VPI changes for IEEE compatibility, which may alter behavior from previous releases. -* Support randomize() class method and rand (#2607). [Krzysztof Bieganski] +* Support randomize() class method and rand (#2607). [Krzysztof Bieganski/Antmicro] **Minor:** @@ -433,7 +466,7 @@ Verilator 4.104 2020-11-14 * Support queue and associative array 'with' statements (#2616). * Support queue slicing (#2326). * Support associative array pattern assignments and defaults. -* Support static methods and typedefs in classes (#2615). [Krzysztof Bieganski] +* Support static methods and typedefs in classes (#2615). [Krzysztof Bieganski/Antmicro] * Add error on typedef referencing self (#2539). [Cody Piersall] * With --debug, turn off address space layout randomization. * Fix iteration over mutating list bug in VPI (#2588). [Kaleb Barrett] diff --git a/Makefile.in b/Makefile.in index 231fbf75b..fc9b6b1a9 100644 --- a/Makefile.in +++ b/Makefile.in @@ -322,7 +322,10 @@ cppcheck: $(CPPCHECK_DEP) $(CPPCHECK) $(CPPCHECK_FLAGS) -DVL_DEBUG=1 -DVL_CPPCHECK=1 -DVL_THREADED=1 $(CPPCHECK_INC) $< CLANGTIDY = clang-tidy -CLANGTIDY_FLAGS = -config='' -checks='-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-init-variables' +CLANGTIDY_FLAGS = -config='' \ + -header-filter='.*' \ + -checks='-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-init-variables,-cppcoreguidelines-avoid-goto,-modernize-avoid-c-arrays,-readability-magic-numbers,-readability-simplify-boolean-expr,-cppcoreguidelines-macro-usage' \ + CLANGTIDY_DEP = $(subst .h,.h.tidy,$(CPPCHECK_H)) \ $(subst .cpp,.cpp.tidy,$(CPPCHECK_CPP)) CLANGTIDY_DEFS = -DVL_DEBUG=1 -DVL_THREADED=1 -DVL_CPPCHECK=1 @@ -331,7 +334,7 @@ clang-tidy: $(CLANGTIDY_DEP) %.cpp.tidy: %.cpp $(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- $(CLANGTIDY_DEFS) $(CPPCHECK_INC) | 2>&1 tee $@ %.h.tidy: %.h - $(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- $(CLANGTIDY_DEFS) $(CPPCHECK_INC) | 2>&1 tee $@ + $(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- $(CLANGTIDY_DEFS) $(CPPCHECK_INC) -x c++-header | 2>&1 tee $@ analyzer-src: -rm -rf src/obj_dbg diff --git a/bin/verilator b/bin/verilator index a50e353bb..62f7be232 100755 --- a/bin/verilator +++ b/bin/verilator @@ -284,33 +284,34 @@ detailed descriptions of these arguments. --bbox-unsup Blackbox unsupported language features --bin Override Verilator binary --build Build model executable/library after Verilation - -CFLAGS C++ compiler arguments for makefile --cc Create C++ output --cdc Clock domain crossing analysis + -CFLAGS C++ compiler arguments for makefile --clk Mark specified signal as clock - --make Generate scripts for specified build tool + --no-clk Prevent marking specified signal as clock --compiler Tune for specified C++ compiler --converge-limit Tune convergence settle time --coverage Enable all coverage --coverage-line Enable line coverage --coverage-max-width Maximum array depth for coverage --coverage-toggle Enable toggle coverage - --coverage-user Enable SVL user coverage --coverage-underscore Enable coverage of _signals + --coverage-user Enable SVL user coverage -D[=] Set preprocessor define --debug Enable debugging --debug-check Enable debugging assertions --no-debug-leak Disable leaking memory in --debug mode --debugi Enable debugging at a specified level --debugi- Enable debugging a source file at a level + --no-decoration Disable comments and symbol decorations --default-language Default language to parse +define+= Set preprocessor define --dpi-hdr-only Only produce the DPI header file --dump-defines Show preprocessor defines with -E --dump-tree Enable dumping .tree files + --dump-tree-addrids Use short identifiers instead of addresses --dump-treei Enable dumping .tree files at a level --dump-treei- Enable dumping .tree file at a source file at a level - --dump-tree-addrids Use short identifiers instead of addresses -E Preprocess, but do not compile --error-limit Abort after this number of errors --exe Link to create executable @@ -321,6 +322,7 @@ detailed descriptions of these arguments. --flatten Force inlining of all modules, tasks and functions -fno- Disable internal optimization stage -G= Overwrite top-level parameter + --gate-stmts Tune gate optimizer depth --gdb Run Verilator under GDB interactively --gdbbt Run Verilator under GDB for backtrace --generate-key Create random key for --protect-key @@ -328,54 +330,50 @@ detailed descriptions of these arguments. --help Display this help --hierarchical Enable hierarchical Verilation -I Directory to search for includes - -j Parallelism for --build - --gate-stmts Tune gate optimizer depth --if-depth Tune IFDEPTH warning +incdir+ Directory to search for includes --inline-mult Tune module inlining --instr-count-dpi Assumed dynamic instruction count of DPI imports - -LDFLAGS Linker pre-object arguments for makefile + -j Parallelism for --build --l2-name Verilog scope name of the top module --language Default language standard to parse + -LDFLAGS Linker pre-object arguments for makefile --lib-create Create a DPI library +libext++[ext]... Extensions for finding modules --lint-only Lint, but do not make output + --make Generate scripts for specified build tool -MAKEFLAGS Arguments to pass to make during --build --max-num-width Maximum number width (default: 64K) - --MMD Create .d dependency files - --MP Create phony dependency targets --Mdir Name of output object directory + --MMD Create .d dependency files --mod-prefix Name to prepend to lower classes - --no-clk Prevent marking specified signal as clock - --no-decoration Disable comments and symbol decorations - --no-pins64 Don't use uint64_t's for 33-64 bit sigs - --no-skip-identical Disable skipping identical output + --MP Create phony dependency targets +notimingchecks Ignored -O0 Disable optimizations -O3 High performance optimizations -O Selectable optimizations -o Name of final executable --no-order-clock-delay Disable ordering clock enable assignments - --no-verilate Skip verilation and just compile previously Verilated code. --output-split Split .cpp files into pieces --output-split-cfuncs Split model functions --output-split-ctrace Split tracing functions -P Disable line numbers and blanks with -E --pins-bv Specify types for top level ports - --pins-sc-uint Specify types for top level ports --pins-sc-biguint Specify types for top level ports + --pins-sc-uint Specify types for top level ports --pins-uint8 Specify types for top level ports + --no-pins64 Don't use uint64_t's for 33-64 bit sigs --pipe-filter Filter all input through a script --pp-comments Show preprocessor comments with -E --prefix Name of top level class + --private Debugging; see docs --prof-c Compile C++ code with profiling --prof-cfuncs Name functions for profiling --prof-exec Enable generating execution profile for gantt chart --prof-pgo Enable generating profiling data for PGO - --protect-key Key for symbol protection --protect-ids Hash identifier names for obscurity + --protect-key Key for symbol protection --protect-lib Create a DPI protected library - --private Debugging; see docs --public Debugging; see docs --public-flat-rw Mark all variables, etc as public_flat_rw -pvalue+= Overwrite toplevel parameter @@ -386,6 +384,7 @@ detailed descriptions of these arguments. --rr Run Verilator and record with rr --savable Enable model save-restore --sc Create SystemC output + --no-skip-identical Disable skipping identical output --stats Create statistics file --stats-vars Provide statistics on variables -sv Enable SystemVerilog parsing @@ -413,6 +412,7 @@ detailed descriptions of these arguments. --unused-regexp Tune UNUSED lint signals -V Verbose version and config -v Verilog library + --no-verilate Skip verilation and just compile previously Verilated code. +verilog1995ext+ Synonym for +1364-1995ext+ +verilog2001ext+ Synonym for +1364-2001ext+ --version Displays program version and exits @@ -427,6 +427,9 @@ detailed descriptions of these arguments. -Wno-lint Disable all lint warnings -Wno-style Disable all style warnings -Wpedantic Warn on compliance-test issues + -Wwarn- Enable specified warning message + -Wwarn-lint Enable lint warning message + -Wwarn-style Enable style warning message --x-assign Assign non-initial Xs to this value --x-initial Assign initial Xs to this value --x-initial-edge Enable initial X->0 and X->1 edge triggers diff --git a/configure.ac b/configure.ac index 03a6e424d..c7ef7c1be 100644 --- a/configure.ac +++ b/configure.ac @@ -5,14 +5,14 @@ # General Public License Version 3 or the Perl Artistic License Version 2.0. # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -#AC_INIT([Verilator],[#.### YYYY-MM-DD]) -#AC_INIT([Verilator],[#.### devel]) -AC_INIT([Verilator],[4.224 2022-06-19], - [https://verilator.org], - [verilator],[https://verilator.org]) # When releasing, also update header of Changes file # and commit using "devel release" or "Version bump" message # Then 'make maintainer-dist' +#AC_INIT([Verilator],[#.### YYYY-MM-DD]) +#AC_INIT([Verilator],[#.### devel]) +AC_INIT([Verilator],[4.226 2022-08-31], + [https://verilator.org], + [verilator],[https://verilator.org]) AC_CONFIG_HEADERS(src/config_build.h) AC_CONFIG_FILES(Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc verilator-config.cmake verilator-config-version.cmake) @@ -355,7 +355,7 @@ AC_SUBST(CFG_CXXFLAGS_PROFILE) #_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++20) #_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++20) case "$(which lsb_release 2>&1 > /dev/null && lsb_release -d)" in -*Ubuntu*22.04*) +*Arch*Linux* | *Ubuntu*22.04*) _MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++17) _MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++17) ;; diff --git a/docs/CONTRIBUTORS b/docs/CONTRIBUTORS index d598cebd5..9c10dbb6f 100644 --- a/docs/CONTRIBUTORS +++ b/docs/CONTRIBUTORS @@ -5,11 +5,13 @@ Please see the Verilator manual for 200+ additional contributors. Thanks to all. Adrien Le Masle Ahmed El-Mahmoudy +Aleksander Kiryk Alex Chadwick Àlex Torregrosa Aliaksei Chapyzhenka Ameya Vikram Singh Andreas Kuster +Arkadiusz Kozdra Chris Randall Chuxuan Wang Conor McCullough @@ -32,6 +34,7 @@ Gianfranco Costamagna Glen Gibb Graham Rushton Guokai Chen +Gustav Svensk Harald Heckmann Howard Su Huang Rui @@ -68,6 +71,7 @@ Lukasz Dalek Maarten De Braekeleer Maciej Sobkowski Marco Widmer +Mariusz Glebocki Markus Krause Marlon James Marshal Qiao @@ -79,6 +83,7 @@ Michaël Lefebvre Mike Popoloski Miodrag Milanović Morten Borup Petersen +Mostafa Gamal Nandu Raj Nathan Kohagen Nathan Myers @@ -95,6 +100,7 @@ Rafal Kapuscik Raynard Qiao Richard Myers Rupert Swarbrick +Ryszard Rozak Samuel Riedel Sean Cross Sebastien Van Cauwenberghe @@ -111,9 +117,11 @@ Tomasz Gorochowik Tymoteusz Blazejczyk Udi Finkelstein Unai Martinez-Corral +Varun Koyyalagunta Vassilis Papaefstathiou Veripool API Bot Victor Besyakov +William D. Jones Wilson Snyder Xi Zhang Yoda Lee diff --git a/docs/guide/connecting.rst b/docs/guide/connecting.rst index edfc3d67b..443702c7d 100644 --- a/docs/guide/connecting.rst +++ b/docs/guide/connecting.rst @@ -86,61 +86,17 @@ Connecting to C++ In C++ output mode (:vlopt:`--cc`), the Verilator generated model class is a simple C++ class. The user must write a C++ wrapper and main loop for the simulation, which instantiates the model class, and link with the Verilated -model. Here is a simple example: +model. -.. code-block:: C++ +Refer to ``examples/make_tracing_c`` in the distribution for a detailed +commented example. - #include // Defines common routines - #include // Need std::cout - #include "Vtop.h" // From Verilating "top.v" +Top level IO signals are read and written as members of the model. You +call the model's :code:`eval()` method to evaluate the model. When the +simulation is complete call the model's :code:`final()` method to execute +any SystemVerilog final blocks, and complete any assertions. See +:ref:`Evaluation Loop`. - Vtop *top; // Instantiation of model - - uint64_t main_time = 0; // Current simulation time - // This is a 64-bit integer to reduce wrap over issues and - // allow modulus. This is in units of the timeprecision - // used in Verilog (or from --timescale-override) - - double sc_time_stamp() { // Called by $time in Verilog - return main_time; // converts to double, to match - // what SystemC does - } - - int main(int argc, char** argv) { - Verilated::commandArgs(argc, argv); // Remember args - - top = new Vtop; // Create model - // Do not instead make Vtop as a file-scope static - // variable, as the "C++ static initialization order fiasco" - // may cause a crash - - top->reset_l = 0; // Set some inputs - - while (!Verilated::gotFinish()) { - if (main_time > 10) { - top->reset_l = 1; // Deassert reset - } - if ((main_time % 10) == 1) { - top->clk = 1; // Toggle clock - } - if ((main_time % 10) == 6) { - top->clk = 0; - } - top->eval(); // Evaluate model - cout << top->out << endl; // Read a output - main_time++; // Time passes... - } - - top->final(); // Done simulating - // // (Though this example doesn't get here) - delete top; - } - - -Note top level IO signals are read and written as members of the model. You -call the :code:`eval()` method to evaluate the model. When the simulation is -complete call the :code:`final()` method to execute any SystemVerilog final -blocks, and complete any assertions. See :ref:`Evaluation Loop`. Connecting to SystemC @@ -449,14 +405,15 @@ accesses the above signal "readme" would be: int main(int argc, char** argv, char** env) { Verilated::commandArgs(argc, argv); - Vour* top = new Vour; - Verilated::internalsDump(); // See scopes to help debug - while (!Verilated::gotFinish()) { + const std::unique_ptr contextp{new VerilatedContext}; + const std::unique_ptr top{new Vour{contextp.get()}}; + + contextp->internalsDump(); // See scopes to help debug + while (!contextp->gotFinish()) { top->eval(); VerilatedVpi::callValueCbs(); // For signal callbacks read_and_check(); } - delete top; return 0; } EOF diff --git a/docs/guide/exe_sim.rst b/docs/guide/exe_sim.rst index 016340cc8..364ac5fba 100644 --- a/docs/guide/exe_sim.rst +++ b/docs/guide/exe_sim.rst @@ -8,7 +8,7 @@ Simulation Runtime Arguments The following are the arguments that may be passed to a Verilated executable, provided that executable calls -:code:`Verilated::commandArgs()`. +:code:`VerilatedContext*->commandArgs(argc, argv)`. All simulation runtime arguments begin with "+verilator", so that the user's executable may skip over all "+verilator" arguments when parsing its @@ -96,7 +96,7 @@ Summary: .. option:: +verilator+noassert Disable assert checking per runtime argument. This is the same as - calling :code:`Verilated::assertOn(false)` in the model. + calling :code:`VerilatedContext*->assertOn(false)` in the model. .. option:: +verilator+V diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index bf99a7d65..0348c4db2 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -129,16 +129,6 @@ Summary: is also used). Verilator manages the build itself, and for this --build requires GNU Make to be available on the platform. -.. option:: -CFLAGS - - Add specified C compiler argument to the generated makefiles. For - multiple flags either pass them as a single argument with space - separators quoted in the shell (:command:`-CFLAGS "-a -b"`), or use - multiple -CFLAGS options (:command:`-CFLAGS -a -CFLAGS -b`). - - When make is run on the generated makefile these will be passed to the - C++ compiler (g++/clang++/msvc++). - .. option:: --cc Specifies C++ without SystemC output mode; see also :vlopt:`--sc` @@ -156,6 +146,16 @@ Summary: have interest in adding more traditional CDC checks, please contact the authors. +.. option:: -CFLAGS + + Add specified C compiler argument to the generated makefiles. For + multiple flags either pass them as a single argument with space + separators quoted in the shell (:command:`-CFLAGS "-a -b"`), or use + multiple -CFLAGS options (:command:`-CFLAGS -a -CFLAGS -b`). + + When make is run on the generated makefile these will be passed to the + C++ compiler (g++/clang++/msvc++). + .. option:: --clk With :vlopt:`--clk`, the specified signal-name is taken as a root clock @@ -179,6 +179,11 @@ Summary: remove it from the combinatorial logic reevaluation checking code. This may greatly improve performance. +.. option:: --no-clk + + Prevent the specified signal from being marked as clock. See + :vlopt:`--clk`. + .. option:: --compiler Enables workarounds for the specified C++ compiler (list below). @@ -288,6 +293,13 @@ Summary: <--debugi>`). Higher levels produce more detailed messages. See :vlopt:`--debug` for other implications of enabling debug. +.. option:: --no-decoration + + When creating output Verilated code, minimize comments, white space, + symbol names and other decorative items, at the cost of greatly reduced + readability. This may assist C++ compile times. This will not typically + change the ultimate model's performance, but may in some cases. + .. option:: --default-language Select the language to be used by default when first processing each @@ -479,6 +491,30 @@ Summary: are typically used only when recommended by a maintainer to help debug or work around an issue. +.. option:: -future0