docs: various howto guides

Author: rickeylev

docs/howto/build-a-wheel.md

@@ -0,0 +1,87 @@
+:::{default-domain} bzl
+:::
+
+# How to build a wheel
+
+This guide explains how to use the `py_wheel` rule to build a wheel
+file from a `py_library`.
+
+## Basic usage
+
+The `py_wheel` rule takes any file-providing target as input and put its files
+into a wheel. Because `py_library` provides its source files, simple cases can
+pass `py_library` directly to `py_wheel`:
+
+```starlark
+# BUILD.bazel
+
+py_library(
+    name = "my_project_lib",
+    srcs = glob(["my_project/**/*.py"]),
+    # ...
+)
+
+py_wheel(
+    name = "my_project_wheel",
+    distribution = "my-project",
+    version = "0.1.0",
+    deps = [":my_project_lib"],
+)
+```
+
+The above will include the *default outputs* of the `py_library`, which are the
+direct `.py` files listed in the py library. It does **not** include transitive
+dependencies.
+
+## Including and filtering transitive dependencies
+
+
+Use the `py_package` rule to include and filter the transitive parts of
+a `py_library` target.
+
+The `py_package` rule has a `packages` attribute that takes a list of dotted
+Python package names to include. All files and dependencies of those packages
+are included.
+
+Here is an example:
+
+```starlark
+# BUILD.bazel
+
+py_library(
+    name = "my_project_lib",
+    srcs = glob(["my_project/**/*.py"]),
+    deps = ["@pypi//some_dep"],
+)
+
+py_package(
+    name = "my_project_package",
+    # This will only include files for the "my_package" package; other files
+    # will be excluded.
+    packages = ["my_project"],
+)
+
+py_wheel(
+    name = "my_project_wheel",
+    distribution = "my-project",
+    version = "0.1.0",
+    # The `py_wheel` rule takes the `py_package` target in the `deps`
+    # attribute.
+    deps = [":my_project_package"],
+)
+```
+
+## Disabling `__init__.py` generation
+
+By default, Bazel automatically creates `__init__.py` files in directories to
+make them importable. This can sometimes be undesirable when building wheels
+because it interfers with namespace packages or makes directories importable
+that shouldn't be importable.
+
+It's highly recommended to disable this behavior by setting a flag in your
+`.bazelrc` file:
+
+```
+# .bazelrc
+build --incompatible_default_to_explicit_init_py=true
+```

docs/howto/get-python-version.md

@@ -0,0 +1,57 @@
+:::{default-domain} bzl
+:::
+
+# How to get the current Python version
+
+This guide explains how to use a [toolchain](toolchains) to get the current Python
+version and, as an example, write it to a file.
+
+You can create a simple rule that accesses the Python toolchain and retrieves
+the version string.
+
+## The rule implementation
+
+Create a file named `my_rule.bzl`:
+
+```text
+# my_rule.bzl
+def _my_rule_impl(ctx):
+    toolchain = ctx.toolchains["@rules_python//python:toolchain_type"]
+    info = toolchain.py3_runtime.interpreter_version_info
+    python_version = str(info.major) + "." + str(info.minor) + "." + str(info.micro)
+
+    output_file = ctx.actions.declare_file(ctx.attr.name + ".txt")
+    ctx.actions.write(
+        output = output_file,
+        content = python_version,
+    )
+
+    return [DefaultInfo(files = depset([output_file]))]
+
+my_rule = rule(
+    implementation = _my_rule_impl,
+    attrs = {},
+    toolchains = ["@rules_python//python:toolchain_type"],
+)
+```
+
+## Using the rule
+
+In your `BUILD.bazel` file, you can use the rule like this:
+
+```text
+# BUILD.bazel
+load(":my_rule.bzl", "my_rule")
+
+my_rule(
+    name = "show_python_version",
+)
+```
+
+When you build this target, it will generate a file named
+`show_python_version.txt` containing the Python version (e.g., `3.9`).
+
+```text
+bazel build :show_python_version
+cat bazel-bin/show_python_version.txt
+```

docs/howto/index.md

@@ -0,0 +1,13 @@
+:::{default-domain} bzl
+:::
+
+# How-to Guides
+
+This section contains a collection of how-to guides for accomplishing specific tasks with `rules_python`.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+*
+```

docs/howto/linking-libpython.md

@@ -0,0 +1,66 @@
+:::{default-domain} bzl
+:::
+
+# How to link to libpython
+
+This guide explains how to use the Python [toolchain](toolchains) to get the linker
+flags required for linking against `libpython`. This is often necessary when
+embedding Python in a C/C++ application.
+
+Currently, the `:current_py_cc_libs` target does *not* include `-lpython` et al
+linker flags. This is intentional because it forces dynamic linking (via the
+dynamic linker processing `DT_NEEDED` entries), which prevents users who want
+to load it in some more custom way.
+
+## Exposing linker flags in a rule
+
+You can create a rule that gets the Python version from the toolchain and
+constructs the correct linker flag. This rule can then provide the flag to
+other C/C++ rules via the `CcInfo` provider.
+
+Here's an example of a rule that creates the `-lpython<version>` flag:
+
+```text
+# python_libs.bzl
+load("@bazel_tools//tools/cpp:toolchain_utils.bzl", "cc_common")
+
+def _python_libs_impl(ctx):
+    toolchain = ctx.toolchains["@rules_python//python:toolchain_type"]
+    info = toolchain.py3_runtime.interpreter_version_info
+    link_flag = "-lpython{}.{}".format(info.major, info.minor)
+
+    cc_info = CcInfo(
+        linking_context = cc_common.create_linking_context(
+            user_link_flags = [link_flag],
+        ),
+    )
+    return [cc_info]
+
+python_libs = rule(
+    implementation = _python_libs_impl,
+    toolchains = ["@rules_python//python:toolchain_type"],
+)
+```
+
+## Using the rule
+
+In your `BUILD.bazel` file, define a target using this rule and add it to the
+`deps` of your `cc_binary` or `cc_library`.
+
+```text
+# BUILD.bazel
+load(":python_libs.bzl", "python_libs")
+
+python_libs(
+    name = "py_libs",
+)
+
+cc_binary(
+    name = "my_app",
+    srcs = ["my_app.c"],
+    deps = [
+        ":py_libs",
+        # Other dependencies
+    ],
+)
+```

docs/howto/pypi-headers.md

@@ -0,0 +1,112 @@
+:::{default-domain} bzl
+:::
+
+# How to expose headers from a PyPI package
+
+When you depend on a PyPI package that includes C headers (like `numpy`), you
+need to make those headers available to your `cc_library` or
+`cc_binary` targets.
+
+The recommended way to do this is to inject a `BUILD.bazel` file into the
+external repository for the package. This `BUILD` file will create
+a `cc_library` target that exposes the header files.
+
+First, create a `.bzl` file that has the extra logic we'll inject. Putting it
+in a separate bzl file avoids having to redownload and extract the whl file
+when our logic changes.
+
+```bzl
+
+# pypi_extra_targets.bzl
+load("@rules_cc//cc:cc_library.bzl", "cc_library")
+
+def extra_numpy_targets():
+    cc_library(
+        name = "headers",
+        hdrs = glob(["**/*.h"]),
+        visibility = ["//visibility:public"],
+    )
+```
+
+## Bzlmod setup
+
+In your `MODULE.bazel` file, use the `build_file_content` attribute of
+`pip.parse` to inject the `BUILD` file content for the `numpy` package.
+
+```bazel
+# MODULE.bazel
+load("@rules_python//python/extensions:pip.bzl", "parse", "whl_mods")
+pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
+whl_mods = use_extension("@rules_python//python/extensions:pip.bzl", "whl_mods")
+
+
+# Define a specific modification for a wheel
+whl_mods(
+    name = "numpy_mods",
+    whl_name = "numpy-1.0.0-py3-none-any.whl", # The exact wheel filename
+    additive_build_content = """
+load("@//:pypi_extra_targets.bzl", "numpy_hdrs")
+
+extra_numpy_targets()
+""",
+)
+pip.parse(
+    hub_name = "pypi",
+    wheel_name = "numpy",
+    requirements_lock = "//:requirements.txt",
+    build_file_content = {
+        "numpy": 'load("//:pypi_extra_targets.bzl", "numpy_hdrs")\n\nnumpy_hdrs()',
+    },
+    whl_modifications = {
+        "@numpy_mods//:numpy.json": "numpy",
+    },
+    extra_hub_aliases = {
+        "numpy": ["headers"],
+    }
+)
+```
+
+## WORKSPACE setup
+
+In your `WORKSPACE` file, use the `annotations` attribute of `pip_parse` to
+inject additional `BUILD` file content, then use `extra_hub_targets` to expose
+that target in the `@pypi` hub repo.
+
+The {obj}`package_annotation` helper can be used to construct the value for the
+`annotations` attribute.
+
+```starlark
+# WORKSPACE
+load("@rules_python//python:pip.bzl", "package_annotation", "pip_parse")
+
+pip_parse(
+    name = "pypi",
+    requirements_lock = "//:requirements.txt",
+    annotations = {
+        "numpy": package_annotation(
+            additive_build_content = """\
+load("@//:pypi_extra_targets.bzl", "numpy_hdrs")
+
+extra_numpy_targets()
+"""
+        ),
+    },
+    extra_hub_targets = {
+        "numpy": ["headers"],
+    },
+)
+```
+
+## Using the headers
+
+In your `BUILD.bazel` file, you can now depend on the generated `headers`
+target.
+
+```bazel
+# BUILD.bazel
+cc_library(
+    name = "my_c_extension",
+    srcs = ["my_c_extension.c"],
+    deps = ["@pypi//numpy:headers"],
+)
+```

docs/howto/python-headers.md

@@ -0,0 +1,30 @@
+:::{default-domain} bzl
+:::
+
+# How to get Python headers for C extensions
+
+When building a Python C extension, you need access to the Python header
+files. This guide shows how to get the necessary include paths from the Python
+[toolchain](toolchains).
+
+The recommended way to get the headers is to depend on the
+`@rules_python//python/cc:current_py_cc_headers` target. This is a helper
+target that uses toolchain resolution to find the correct headers for the
+target platform.
+
+## Using the headers
+
+In your `BUILD.bazel` file, you can add `@rules_python//python/cc:current_py_cc_headers`
+to the `deps` of a `cc_library` or `cc_binary` target.
+
+```bazel
+# BUILD.bazel
+cc_library(
+    name = "my_c_extension",
+    srcs = ["my_c_extension.c"],
+    deps = ["@rules_python//python/cc:current_py_cc_headers"],
+)
+```
+
+This setup ensures that your C extension code can find and use the Python
+headers during compilation.

docs/index.md

@@ -102,6 +102,7 @@ precompiling
 gazelle
 REPL <repl>
 Extending <extending>
+How-to Guides <howto/index>
 Contributing <contributing>
 devguide
 support