Add more instructions in HACKING.md

It's been long since it was updated or refined, and it was a bit too vague in certain areas. Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Tom Cosgrove <tom.cosgrove@arm.com> (Merged from https://github.com/openssl/openssl/pull/27674) (cherry picked from commit 8bd89f15c9)
2025-12-20 01:22:19 +08:00 · 2025-05-21 08:22:50 +02:00
parent 240228979b
commit 037ad3b70e
1 changed files with 67 additions and 20 deletions
--- a/HACKING.md
+++ b/HACKING.md
@@ -1,33 +1,80 @@
 MODIFYING OPENSSL SOURCE
 ========================

-This document describes the way to add custom modifications to OpenSSL sources.
+This document describes the way to add custom modifications to OpenSSL
+sources.

- If you are adding new public functions to the custom library build, you need to
- either add a prototype in one of the existing OpenSSL header files;
- or provide a new header file and edit
- [Configurations/unix-Makefile.tmpl](Configurations/unix-Makefile.tmpl)
- to pick up that file.
+If you are adding new C source files
+------------------------------------

- After that, perform the following steps:
+Please update the `build.info` files in the directories where you placed the
+C source files, to include a line like this for each new C source file:
+
+-   In `crypto/` or any of its subdirectories (intended for `libcrypto`):
+
+        SOURCE[../libcrypto]={name-of-C-source-file}
+
+-   In `ssl/` or any of its subdirectories (intended for `libssl`):
+
+        SOURCE[../libssl]={name-of-C-source-file}
+
+Do note that the path given as the `SOURCE` attribute must be adapted
+appropriately for the location of the `build.info` file, as it's a relative
+path to where the library itself is built, for example:
+
+-   For `crypto/build.info`, the library path should be `../libcrypto`
+-   For `crypto/evp/build.info`, the library path should be
+    `../../libcrypto`
+-   For `ssl/build.info`, the library path should be `../libssl`
+-   For `ssl/quic/build.info`, the library path should be `../../libssl`
+
+To know more about `build.info` files, please read [doc/internal/man7/build.info.pod].
+For better viewing, consider converting it to HTML or PDF using `pod2html`
+or `pod2pdf`.
+
+Adding new public functions
+---------------------------
+
+If you are adding new public functions to the custom library build, you need to
+either add a prototype in one of the existing OpenSSL header files, or
+provide a new header file and edit.
+
+Only headers in the `include/openssl` subdirectory are considered for public
+functions.  If you're creating a new header file, it must be located in that
+directory.
+
+Functions declared in `include/openssl` header files are assumed to be part
+of the `libcrypto` library unless specified otherwise.  *If your new
+functions are meant for the `libssl` library*, you will need to edit
+[Configurations/unix-Makefile.tmpl] and add the header file name in the
+array `my @sslheaders_tmpl`.
+
+Updating OpenSSL's bookkeeping files
+------------------------------------
+
+OpenSSL has a few bookkeeping files to keep track of exposed functions, most
+importantly `util/libcrypto.num` and `util/libssl.num`.  Any time a new
+public function - as defined above - is added, these files must be updated.
+
+To make such an update, please do the following:

    ./Configure -Werror --strict-warnings [your-options]
    make update
-    make
-    make test

- `make update` ensures that your functions declarations are added to
- `util/libcrypto.num` or `util/libssl.num`.
- If you plan to submit the changes you made to OpenSSL
- (see [CONTRIBUTING.md](CONTRIBUTING.md)), it's worth running:
+If you plan to submit the changes you made to OpenSSL (see
+[CONTRIBUTING.md]), it's also worth running the following after running
+`make update`, to ensure that documentation has correct format.

    make doc-nits

- after running `make update` to ensure that documentation has correct format.
+Do note that `make update` also generates files related to OIDs (in the
+`crypto/objects/`  folder) and errors messages.

- `make update` also generates files related to OIDs (in the `crypto/objects/`
- folder) and errors.
- If a merge error occurs in one of these generated files, then the
- generated files need to be removed and regenerated using `make update`.
- To aid in this process, the generated files can be committed separately
- so they can be removed easily.
+If a git merge error occurs in one of these generated files, then the
+generated files need to be removed and regenerated using `make update`.
+To aid in this process, the generated files can be committed separately
+so they can be removed easily by reverting that commit.
+
+[doc/internal/man7/build.info.pod]: ./doc/internal/man7/build.info.pod
+[Configurations/unix-Makefile.tmpl]: ./Configurations/unix-Makefile.tmpl
+[CONTRIBUTING.md]: ./CONTRIBUTING.md