xref: /aosp_15_r20/external/pigweed/third_party/boringssl/docs.rst (revision 61c4878ac05f98d0ceed94b57d316916de578985) 
1.. _module-pw_third_party_boringssl:
2
3=========
4BoringSSL
5=========
6
7The ``$dir_pw_third_party/boringssl`` module provides the build files to
8compile and use BoringSSL. The source code of BoringSSL needs to be provided by
9the user. It is recommended to download it via Git submodules.
10
11-------------
12Build support
13-------------
14
15This module provides support to compile BoringSSL with GN. This is required when
16compiling backends modules that use BoringSSL, such as some facades in
17:ref:`module-pw_crypto`
18
19Submodule
20=========
21
22The recommended way to include BoringSSL source code is to add it as a
23submodule:
24
25.. code-block:: sh
26
27   git submodule add https://boringssl.googlesource.com/boringssl/ \
28       third_party/boringssl/src
29
30GN
31==
32The GN build file depends on a generated file called ``BUILD.generated.gni``
33with the list of the different types of source files for the selected BoringSSL
34version.
35
36.. code-block:: sh
37
38   cd third_party/boringssl
39   python src/util/generate_build_files.py gn
40
41The GN variables needed are defined in
42``$dir_pw_third_party/boringssl/boringssl.gni``:
43
44#. Set the GN ``dir_pw_third_party_boringssl`` to the path of the BoringSSL
45   installation.
46
47   - If using the submodule path from above, add the following to the
48     ``default_args`` in the project's ``.gn``:
49
50     .. code-block::
51
52        dir_pw_third_party_boringssl = "//third_party/boringssl/src"
53
54#. Having a non-empty ``dir_pw_third_party_boringssl`` variable causes GN to
55   attempt to include the ``BUILD.generated.gni`` file from the sources even
56   during the bootstrap process before the source package is installed by the
57   bootstrap process. To avoid this problem, set this variable to the empty
58   string during bootstrap by adding it to the ``virtualenv.gn_args`` setting in
59   the ``env_setup.json`` file:
60
61   .. code-block:: json
62
63      {
64        "virtualenv": {
65          "gn_args": [
66            "dir_pw_third_party_boringssl=\"\""
67          ]
68        }
69      }
70
71#. Alternatively, set the GN ``pw_third_party_boringssl_ALIAS`` to your
72   boringssl build target if you would like to use your own build target instead
73   of the one provided by Pigweed. This should be used instead of
74   ``dir_pw_third_party_boringssl``. This fixes diamond dependency conflicts
75   caused by two build targets using the same source files.
76
77After this is done a ``pw_source_set`` for the BoringSSL library is created at
78``$dir_pw_third_party/boringssl``.
79