Suggested Documentation Changes to "Tutorial: Hello, XLS!"

[miwilliams]

doc link

• Installation and Building

  • Include bazel website link; there is a link on the main project page, but not here

  • There's a section that says "Binary releases are coming soon"; add a link to Install Using Conda

  • My initial attempt to build from source failed with Executing genrule @z3//:gen_src/tactic/smtlogics/qfufbv_tactic_params [for tool] failed: (Exit 127): bash failed: error executing command (from target @z3//:gen_src/tactic/smtlogics/qfufbv_tactic_params) /bin/bash -c ... (remaining 1 argument skipped); re-executing with bazel build -c opt xls/... --sandbox_debug and looking at the logs, I spotted /bin/bash: line 1: python: command not found; I aliased python to /usr/bin/python3 and hoped for the best and it worked. We should include dependency on python 2.x in the description or fix the build to gracefully handle python3. python3 is called out as a specific dependency on the main project page (see commit eb2fb6d81523b09fbd77b63b88381b1ad6c74850 for more context)

  • During the build, there are many noisy compiler warnings from the external packages, but also from XLS code too (built with bazel 7.0.0, synced to commit 0bbb0a9):

    • xls/common/logging/logging.cc:50:13: warning: unused function 'MakeCheckOpValueString' [-Wunused-function]
    • xls/common/logging/logging.cc:58:13: warning: unused function 'MakeCheckOpValueString' [-Wunused-function]
    • xls/common/logging/logging.cc:66:13: warning: unused function 'MakeCheckOpValueString' [-Wunused-function]
    • xls/dslx/stdlib/float32_test.cc:61:18: warning: implicit conversion from 'type' (aka 'int') to 'float' changes value from 2147483647 to 2147483648 [-Wimplicit-const-int-float-conversion]
    • xls/netlist/interpreter_test.cc:547:43: warning: use of bitwise '&' with boolean operands [-Wbitwise-instead-of-logical]
    • xls/netlist/interpreter_test.cc:548:42: warning: use of bitwise '|' with boolean operands [-Wbitwise-instead-of-logical]
    • xls/noc/config_ng/flattened_multi_dimensional_array_test.cc:43:16: warning: variable 'element' set but not used [-Wunused-but-set-variable]
    • xls/tools/benchmark_main.cc:685:60: warning: captured structured bindings are a C++20 extension [-Wc++20-extensions]
    • bazel-out/k8-opt/bin/xls/build_rules/tests/type_definitions_types_cpp.cc:15:13: warning: unused function 'FitsInNBitsSigned' [-Wunused-function]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_10.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_11.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_12.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_13.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_14.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_15.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_16.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_17.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • bazel-out/k8-opt/bin/xls/contrib/xlscc/unit_tests/sample_fuzz_18.cc:5:9: warning: unknown pragma ignored [-Wunknown-pragmas]
    • xls/common/logging/logging.cc:42:13: warning: unused function 'MakeCheckOpValueString' [-Wunused-function]
    • xls/common/status/status_macros_test.cc:117:30: warning: variable 't6' set but not used [-Wunused-but-set-variable]
    • xls/dslx/stdlib/float32_test.cc:53:36: warning: implicit conversion from 'type' (aka 'int') to 'float' changes value from 2147483647 to 2147483648 [-Wimplicit-const-int-float-conversion]
    • xls/fuzzer/cpp_run_fuzz.cc:47:14: warning: unused function 'WriteToFile' [-Wunused-function]
    • xls/ir/bits_test.cc:535:20: warning: unused function 'BytesToHexString' [-Wunused-function]
    • ./xls/jit/function_base_jit.h:184:17: warning: private field 'function_base_' is not used [-Wunused-private-field]
    • xls/jit/switchable_function_jit.cc:43:2: warning: XLS JIT is currently disabled via EMERGENCY_FORCE_INTERPRETER and by default won't be used. [-W#warnings]
    • xls/modules/aes/aes_test_common.cc:108:13: warning: unused function 'InitVectorToBuffer' [-Wunused-function]
    • ./xls/netlist/interpreter.h:327:34: warning: reading variable 'num_available_threads_' requires holding mutex 'input_queue_guard_' [-Wthread-safety-analysis]
    • xls/noc/config_ng/flattened_multi_dimensional_array_test.cc:35:16: warning: variable 'element' set but not used [-Wunused-but-set-variable]
    • xls/passes/narrowing_pass_test.cc:47:26: warning: unused variable 'kProverTimeout' [-Wunused-const-variable]
    • xls/tools/benchmark_main.cc:612:60: warning: captured structured bindings are a C++20 extension [-Wc++20-extensions]

• Create Your Module

  • It appears to work fine if hello_xls.x is created outside of the repo root directory, which I think is actually better anyway so that the user isn't cluttering up the root dir with untracked files

• Say hello, XLS!

  • Tell the user that they can exit the repl via ctrl-d (exit quit and help don't do anything)

  • The test text does not appear to output the trace string; it does appear in the log, so users should be instructed to execute the test with --alsologtostderr or else the trace function should also write to stdout