xref: /aosp_15_r20/external/bazelbuild-rules_python/docs/getting-started.md (revision 60517a1edbc8ecf509223e9af94a7adec7d736b8) 
1# Getting started
2
3This doc is a simplified guide to help get started started quickly. It provides
4a simplified introduction to having a working Python program for both bzlmod
5and the older way of using `WORKSPACE`.
6
7It assumes you have a `requirements.txt` file with your PyPI dependencies.
8
9For more details information about configuring `rules_python`, see:
10* [Configuring the runtime](toolchains)
11* [Configuring third party dependencies (pip/pypi)](pypi-dependencies)
12* [API docs](api/index)
13
14## Using bzlmod
15
16The first step to using rules_python with bzlmod is to add the dependency to
17your MODULE.bazel file:
18
19```starlark
20# Update the version "0.0.0" to the release found here:
21# https://github.com/bazelbuild/rules_python/releases.
22bazel_dep(name = "rules_python", version = "0.0.0")
23
24pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
25pip.parse(
26    hub_name = "my_deps",
27    python_version = "3.11",
28    requirements_lock = "//:requirements.txt",
29)
30use_repo(pip, "my_deps")
31```
32
33## Using a WORKSPACE file
34
35Using WORKSPACE is deprecated, but still supported, and a bit more involved than
36using Bzlmod. Here is a simplified setup to download the prebuilt runtimes.
37
38```starlark
39load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
40
41
42# Update the SHA and VERSION to the lastest version available here:
43# https://github.com/bazelbuild/rules_python/releases.
44
45SHA="84aec9e21cc56fbc7f1335035a71c850d1b9b5cc6ff497306f84cced9a769841"
46
47VERSION="0.23.1"
48
49http_archive(
50    name = "rules_python",
51    sha256 = SHA,
52    strip_prefix = "rules_python-{}".format(VERSION),
53    url = "https://github.com/bazelbuild/rules_python/releases/download/{}/rules_python-{}.tar.gz".format(VERSION,VERSION),
54)
55
56load("@rules_python//python:repositories.bzl", "py_repositories")
57
58py_repositories()
59
60load("@rules_python//python:repositories.bzl", "python_register_toolchains")
61
62python_register_toolchains(
63    name = "python_3_11",
64    # Available versions are listed in @rules_python//python:versions.bzl.
65    # We recommend using the same version your team is already standardized on.
66    python_version = "3.11",
67)
68
69load("@python_3_11//:defs.bzl", "interpreter")
70
71load("@rules_python//python:pip.bzl", "pip_parse")
72
73pip_parse(
74    ...
75    python_interpreter_target = interpreter,
76    ...
77)
78```
79
80## "Hello World"
81
82Once you've imported the rule set using either Bzlmod or WORKSPACE, you can then
83load the core rules in your `BUILD` files with the following:
84
85```starlark
86load("@rules_python//python:defs.bzl", "py_binary")
87
88py_binary(
89  name = "main",
90  srcs = ["main.py"],
91  deps = [
92      "@my_deps//foo",
93      "@my_deps//bar",
94  ]
95)
96```
97