Skip to content

Commit

Permalink
🖋️ Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@neqochan
neqochan committed Jul 1, 2022
1 parent ed2d95e commit 62f5d95
Show file tree
Hide file tree
Showing 17 changed files with 175 additions and 120 deletions.
2 changes: 1 addition & 1 deletion MODULE.bazel
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
module(
name = "rules_ll",
version = "20220624.0",
version = "20220701.0",
execution_platforms_to_register = [
"@rules_ll//ll:ll_linux_exec_platform",
],
Expand Down
2 changes: 1 addition & 1 deletion README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ workspace:
touch WORKSPACE.bazel .bazelrc
echo cbb4eb1973a7fb49d15ced3fea6498f714f3ab0c >> .bazelversion
echo 'bazel_dep(name="rules_ll", version="20220624.0")' >> MODULE.bazel
echo 'bazel_dep(name="rules_ll", version="20220701.0")' >> MODULE.bazel
Copy the following lines into the just created ``.bashrc`` file::

Expand Down
18 changes: 8 additions & 10 deletions docs/_sources/args.md.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,12 +111,12 @@ link_executable_args(<a href="#link_executable_args-ctx">ctx</a>, <a href="#link
| <a id="link_executable_args-mode"></a>mode | <p align="center"> - </p> | none |


<a id="#link_shared_object_args"></a>
<a id="#llvm_bindir_path"></a>

## link_shared_object_args
## llvm_bindir_path

<pre>
link_shared_object_args(<a href="#link_shared_object_args-ctx">ctx</a>, <a href="#link_shared_object_args-in_files">in_files</a>, <a href="#link_shared_object_args-out_file">out_file</a>)
llvm_bindir_path(<a href="#llvm_bindir_path-ctx">ctx</a>)
</pre>


Expand All @@ -126,17 +126,15 @@ link_shared_object_args(<a href="#link_shared_object_args-ctx">ctx</a>, <a href=

| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="link_shared_object_args-ctx"></a>ctx | <p align="center"> - </p> | none |
| <a id="link_shared_object_args-in_files"></a>in_files | <p align="center"> - </p> | none |
| <a id="link_shared_object_args-out_file"></a>out_file | <p align="center"> - </p> | none |
| <a id="llvm_bindir_path-ctx"></a>ctx | <p align="center"> - </p> | none |


<a id="#llvm_bindir_path"></a>
<a id="#llvm_gendir_path"></a>

## llvm_bindir_path
## llvm_gendir_path

<pre>
llvm_bindir_path(<a href="#llvm_bindir_path-ctx">ctx</a>)
llvm_gendir_path(<a href="#llvm_gendir_path-ctx">ctx</a>)
</pre>


Expand All @@ -146,7 +144,7 @@ llvm_bindir_path(<a href="#llvm_bindir_path-ctx">ctx</a>)

| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="llvm_bindir_path-ctx"></a>ctx | <p align="center"> - </p> | none |
| <a id="llvm_gendir_path-ctx"></a>ctx | <p align="center"> - </p> | none |


<a id="#llvm_target_directory_path"></a>
Expand Down
6 changes: 4 additions & 2 deletions docs/_sources/defs.md.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ load("@rules_ll//ll:defs.bzl", "ll_binary")
<pre>
ll_binary(<a href="#ll_binary-name">name</a>, <a href="#ll_binary-angled_includes">angled_includes</a>, <a href="#ll_binary-compilation_mode">compilation_mode</a>, <a href="#ll_binary-compile_flags">compile_flags</a>, <a href="#ll_binary-data">data</a>, <a href="#ll_binary-defines">defines</a>, <a href="#ll_binary-deps">deps</a>, <a href="#ll_binary-hdrs">hdrs</a>,
<a href="#ll_binary-includes">includes</a>, <a href="#ll_binary-libraries">libraries</a>, <a href="#ll_binary-link_flags">link_flags</a>, <a href="#ll_binary-llvm_project_deps">llvm_project_deps</a>, <a href="#ll_binary-relative_angled_includes">relative_angled_includes</a>,
<a href="#ll_binary-relative_includes">relative_includes</a>, <a href="#ll_binary-srcs">srcs</a>, <a href="#ll_binary-toolchain_configuration">toolchain_configuration</a>)
<a href="#ll_binary-relative_includes">relative_includes</a>, <a href="#ll_binary-sanitize">sanitize</a>, <a href="#ll_binary-srcs">srcs</a>, <a href="#ll_binary-toolchain_configuration">toolchain_configuration</a>)
</pre>


Expand Down Expand Up @@ -52,6 +52,7 @@ Example:
| <a id="ll_binary-llvm_project_deps"></a>llvm_project_deps | <code>cc_library</code> deps from the LLVM project overlay.<br><br> Using this attribute causes compile actions to add <code>-idirafter</code> include paths to <code>clang/include</code> and <code>llvm/include</code> for Clang/LLVM internal and generated headers.<br><br> Dependencies declared in this attribute will be compiled for the <code>target</code> platform using the original <code>rules_cc</code> overlay targets.<br><br> This attribute hijacks cc_library. Use with caution. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a id="ll_binary-relative_angled_includes"></a>relative_angled_includes | Additional angled include paths, relative to the target workspace.<br><br> This attribute is useful if we require custom include prefix stripping, but have dynamic paths, such as ones generated by <code></code>bzlmod<code></code>. So instead of using <code></code>angled_includes = ["external/mydep.someversion/include"]<code></code> we can use <code></code>relative_angled_includes = ["include"]<code></code>, and the path to the workspace will be added automatically.<br><br> Only used for this target. | List of strings | optional | [] |
| <a id="ll_binary-relative_includes"></a>relative_includes | Additional quoted include paths, relative to the target workspace.<br><br> This attribute is useful if we require custom include prefix stripping, but have dynamic paths, such as ones generated by <code></code>bzlmod<code></code>. So instead of using <code></code>includes = ["external/mydep.someversion/include"]<code></code> we can use <code></code>relative_includes = ["include"]<code></code>, and the path to the workspace will be added automatically.<br><br> Only used for this target. | List of strings | optional | [] |
| <a id="ll_binary-sanitize"></a>sanitize | Enable sanitizers for this target.<br><br> Some sanitizers come with heavy performance penalties. Use <code>config_setting</code>s to only use them in debug builds. Many combinations of multiple enabled sanitizers are invalid. If possible, use one at a time.<br><br> <code>"address"</code>: Enable AddressSanitizer to detect memory errors. Typical slowdown introduced is 2x. Executables that invoke CUDA-based kernels, including those created via HIP and SYCL, need to be run with <code>ASAN_OPTIONS=protect_shadow_gap=0</code>. <code>"leak"</code>: Enable LeakSanitizer to detect memory leaks. This is already integrated in AddressSanitizer. Enable LeakSanitizer if you want to use it in standalone mode. Almost no performance overhead until the end of the process where leaks are detected. <code>"memory"</code>: Enable MemorySanitizer to detect uninitialized reads. Typical slowdown introduced is 3x. Add <code>"-fsanitize-memory-track-origins=2"</code> to the <code>compile_flags</code> attribute to track the origins of uninitialized values. <code>"undefined_behavior"</code>: Enable UndefinedBehaviorSanitizer to detect undefined behavior. Small performance overhead. <code>"thread"</code>: Enable ThreadSanitizer to detect data races. Typical slowdown is 5x-15x. Typical memory overhead is 5x-10x. ThreadSanitizer is nondeterminisic. Run sanitized executables multiple times and build them with different optimization levels. | List of strings | optional | [] |
| <a id="ll_binary-srcs"></a>srcs | Compilable source files for this target.<br><br> Only compilable files and object files <code>[".ll", ".o", ".S", ".c", ".cl", ".cpp"]</code> are allowed here.<br><br> Headers should be placed in the <code>hdrs</code> attribute. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a id="ll_binary-toolchain_configuration"></a>toolchain_configuration | TODO | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //ll:current_ll_toolchain_configuration |

Expand Down Expand Up @@ -94,7 +95,7 @@ An example project using this rule is available at
<pre>
ll_library(<a href="#ll_library-name">name</a>, <a href="#ll_library-angled_includes">angled_includes</a>, <a href="#ll_library-bitcode_libraries">bitcode_libraries</a>, <a href="#ll_library-bitcode_link_flags">bitcode_link_flags</a>, <a href="#ll_library-compilation_mode">compilation_mode</a>,
<a href="#ll_library-compile_flags">compile_flags</a>, <a href="#ll_library-data">data</a>, <a href="#ll_library-defines">defines</a>, <a href="#ll_library-deps">deps</a>, <a href="#ll_library-emit">emit</a>, <a href="#ll_library-hdrs">hdrs</a>, <a href="#ll_library-includes">includes</a>, <a href="#ll_library-llvm_project_deps">llvm_project_deps</a>,
<a href="#ll_library-relative_angled_includes">relative_angled_includes</a>, <a href="#ll_library-relative_includes">relative_includes</a>, <a href="#ll_library-shared_object_link_flags">shared_object_link_flags</a>, <a href="#ll_library-srcs">srcs</a>,
<a href="#ll_library-relative_angled_includes">relative_angled_includes</a>, <a href="#ll_library-relative_includes">relative_includes</a>, <a href="#ll_library-sanitize">sanitize</a>, <a href="#ll_library-shared_object_link_flags">shared_object_link_flags</a>, <a href="#ll_library-srcs">srcs</a>,
<a href="#ll_library-toolchain_configuration">toolchain_configuration</a>, <a href="#ll_library-transitive_angled_includes">transitive_angled_includes</a>, <a href="#ll_library-transitive_defines">transitive_defines</a>, <a href="#ll_library-transitive_hdrs">transitive_hdrs</a>,
<a href="#ll_library-transitive_includes">transitive_includes</a>, <a href="#ll_library-transitive_relative_angled_includes">transitive_relative_angled_includes</a>, <a href="#ll_library-transitive_relative_includes">transitive_relative_includes</a>)
</pre>
Expand Down Expand Up @@ -131,6 +132,7 @@ Example:
| <a id="ll_library-llvm_project_deps"></a>llvm_project_deps | <code>cc_library</code> deps from the LLVM project overlay.<br><br> Using this attribute causes compile actions to add <code>-idirafter</code> include paths to <code>clang/include</code> and <code>llvm/include</code> for Clang/LLVM internal and generated headers.<br><br> Dependencies declared in this attribute will be compiled for the <code>target</code> platform using the original <code>rules_cc</code> overlay targets.<br><br> This attribute hijacks cc_library. Use with caution. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a id="ll_library-relative_angled_includes"></a>relative_angled_includes | Additional angled include paths, relative to the target workspace.<br><br> This attribute is useful if we require custom include prefix stripping, but have dynamic paths, such as ones generated by <code></code>bzlmod<code></code>. So instead of using <code></code>angled_includes = ["external/mydep.someversion/include"]<code></code> we can use <code></code>relative_angled_includes = ["include"]<code></code>, and the path to the workspace will be added automatically.<br><br> Only used for this target. | List of strings | optional | [] |
| <a id="ll_library-relative_includes"></a>relative_includes | Additional quoted include paths, relative to the target workspace.<br><br> This attribute is useful if we require custom include prefix stripping, but have dynamic paths, such as ones generated by <code></code>bzlmod<code></code>. So instead of using <code></code>includes = ["external/mydep.someversion/include"]<code></code> we can use <code></code>relative_includes = ["include"]<code></code>, and the path to the workspace will be added automatically.<br><br> Only used for this target. | List of strings | optional | [] |
| <a id="ll_library-sanitize"></a>sanitize | Enable sanitizers for this target.<br><br> Some sanitizers come with heavy performance penalties. Use <code>config_setting</code>s to only use them in debug builds. Many combinations of multiple enabled sanitizers are invalid. If possible, use one at a time.<br><br> <code>"address"</code>: Enable AddressSanitizer to detect memory errors. Typical slowdown introduced is 2x. Executables that invoke CUDA-based kernels, including those created via HIP and SYCL, need to be run with <code>ASAN_OPTIONS=protect_shadow_gap=0</code>. <code>"leak"</code>: Enable LeakSanitizer to detect memory leaks. This is already integrated in AddressSanitizer. Enable LeakSanitizer if you want to use it in standalone mode. Almost no performance overhead until the end of the process where leaks are detected. <code>"memory"</code>: Enable MemorySanitizer to detect uninitialized reads. Typical slowdown introduced is 3x. Add <code>"-fsanitize-memory-track-origins=2"</code> to the <code>compile_flags</code> attribute to track the origins of uninitialized values. <code>"undefined_behavior"</code>: Enable UndefinedBehaviorSanitizer to detect undefined behavior. Small performance overhead. <code>"thread"</code>: Enable ThreadSanitizer to detect data races. Typical slowdown is 5x-15x. Typical memory overhead is 5x-10x. ThreadSanitizer is nondeterminisic. Run sanitized executables multiple times and build them with different optimization levels. | List of strings | optional | [] |
| <a id="ll_library-shared_object_link_flags"></a>shared_object_link_flags | Additional flags for the linker when emitting shared objects.<br><br> Only used if <code>emit</code> includes <code>"shared_object"</code>. | List of strings | optional | [] |
| <a id="ll_library-srcs"></a>srcs | Compilable source files for this target.<br><br> Only compilable files and object files <code>[".ll", ".o", ".S", ".c", ".cl", ".cpp"]</code> are allowed here.<br><br> Headers should be placed in the <code>hdrs</code> attribute. | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
| <a id="ll_library-toolchain_configuration"></a>toolchain_configuration | TODO | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //ll:current_ll_toolchain_configuration |
Expand Down
Loading

0 comments on commit 62f5d95

Please sign in to comment.