google / google/xls

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

Open
#1,247 0 comments 0 reactions 1 assignee Claimed by @proppy View on GitHub
documentation
Dominant language
C++
Stars
1.9k
Forks
283
Avg merge
2d 10h
Merged PRs (30d)
135

Description

[doc link](https://google.github.io/xls/tutorials/hello_xls/)

* Installation and Building
* Include [bazel website link](https://bazel.build/install); 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](https://github.com/google/xls?tab=readme-ov-file#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](https://github.com/google/xls/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 0bbb0a9c45d62f4d5086059e7a3fa498a708a191):

* 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`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.