[PATCH] doc: updates to README

[PATCH] doc: updates to README

[Kris Van Hees]

Remove obsolete reference to kernel source and headers for building
DTrace.

Move build instructions for pre-1.13.2 versions to a new file.

Signed-off-by: Kris Van Hees <kris.van.hees@oracle.com>
---
 README.md         |  86 ++------------------------
 README.pre-1.13.2 | 152 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 156 insertions(+), 82 deletions(-)
 create mode 100644 README.pre-1.13.2

diff --git a/README.md b/README.md
index 9c506694..5855a55a 100644
--- a/README.md
+++ b/README.md
@@ -128,24 +128,9 @@ make BPFC=bpf-gcc BPFLD=bpf-ld
 sudo make install
 ```
 
-In this scenario the build system expects that kernel sources can be found at
-`/lib/modules/$(uname -r)/build`.  It is also expected that the kernel used for
-userspace build is compatible with the utils (the exported userspace headers in
-the `include/uapi/linux/dtrace` are compatible with the utils version being
-built).
-
-You can point at a different kernel version with the KERNELS variable, e.g.
-```
-make KERNELS="5.16.8"
-```
-as long as the source tree that kernel was built with remains where it was
-when that kernel was installed.
-
 See `./configure --help`, `make help`, and the top-level GNUmakefile for a
-full list of options (building translators against multiple different
-kernels at once, building against kernel sources found in different places,
-building against a kernel built with O=, installing in different places,
-etc.)
+full list of options (installing in different places, building translators for
+kernels, etc.)
 
 Some of the options (e.g., those specifying paths) may need to be specified
 when installing as well as when building.  To avoid this, you can use the
@@ -200,68 +185,5 @@ Support for DTrace is included in Oracle Linux support subscriptions. Individual
 
 ## 7. Building Previous Releases of DTrace
 
-For versions of DTrace prior to 2.0.0-1.13.2 a small number of kernel patches
-patches are needed, which are
-[here](https://github.com/oracle/dtrace-linux-kernel).  Branches named
-starting v2/* are suitable.
-
-To build such versions of dtrace follow the steps below.
-
-### 7.1. Prerequisites
-
-See [above](#21-prerequisites).
-
-At this point, you will need an additional step:
-
-### 7.2. Build a kernel with add-on features that DTrace uses
-
-DTrace 2.0.0-1.13.1 and earlier depend on a few extra kernel features that are
-not available in the upstream kernel:
-
-- CTF type information extraction
-- /proc/kallmodsyms
-- New system call: waitfd()
-
-As noted above, patches that implement these features are available from the
-v2/* branches in our Linux kernel repository for features that DTrace uses:
-https://github.com/oracle/dtrace-linux-kernel
-
-The customary way to obtain these patches is to clone an appropriate upstream
-kernel version (5.8.1 or later) and to merge our
-[updated tree](https://github.com/oracle/dtrace-linux-kernel/tree/v2/5.8.1)
-into it.  The patch set is quite small, but may need some tweaking if it is
-being merged into a newer tree.  We occasionally push a new patched tree to our
-github repo, so do look around the repo to see if there is a branch with better
-match.
-
-Oracle Linux's [UEK7](https://github.com/oracle/linux-uek/tree/uek7/ga)
-provides a simple alternative if you don't want to patch your own kernel.
-
-Building of a patched kernel from sources is also straightforward.
-Please consult `Documentation/process/changes.rst` in the kernel source tree
-to ensure all required dependencies are installed first.  The following steps
-should build and install the kernel.
-
-```
-# Start with your preferred .config options.  Features DTrace needs should
-# enable themselves automatically.
-make olddefconfig
-make
-
-# This step will produce vmlinux.ctfa, which holds all CTF data for the kernel
-# and its modules.  If it doesn't work, you don't have a toolchain that is
-# recent enough.
-make ctf
-
-# Install with root privileges.
-sudo make INSTALL_MOD_STRIP=1 modules_install
-sudo make install
-```
-
-It is preferred (but not required) to reboot into your new kernel before
-trying to build DTrace.  (If you don't reboot into it, you need to specify
-some extra options when running make.)
-
-### 7.3. Build DTrace
-
-See [above](#22-build-dtrace).
+Refer to [these instructions](./README.pre-1.13.2.md) to build DTrace versions
+prior to 2.0.0-1.13.2.
diff --git a/README.pre-1.13.2 b/README.pre-1.13.2
new file mode 100644
index 00000000..1509ec65
--- /dev/null
+++ b/README.pre-1.13.2
@@ -0,0 +1,152 @@
+ Linux DTrace
+
+For versions of DTrace prior to 2.0.0-1.13.2 a small number of kernel patches
+patches are needed, which are
+[here](https://github.com/oracle/dtrace-linux-kernel).  Branches named
+starting v2/* are suitable.
+
+To build such versions of dtrace follow the steps below.
+
+## 1. Prerequisites
+
+Please read this section carefully before moving over to the build
+documentation to ensure your environment is properly configured.
+
+### 1.1. Verify that binutils is recent enough...
+
+DTrace uses a type introspection system called CTF.  This is supported by
+upstream GCC and GNU Binutils.  Make sure you have binutils 1.36 or later
+installed.
+
+If your distro provides libctf.so in a binutils development package, you need
+to install that too.
+
+### 1.2. or install a recent-enough binutils
+
+If your distro provides binutils 1.36 or later, you should install it.  If not,
+you can build your own local copy (which can be configured with a --prefix
+specific to itself to avoid disturbing the distro version).
+
+### 1.3. Install other necessary packages
+
+A few other packages are required, either for building or at runtime.  They
+should be part of most Linux distributions today and can be installed via the
+package manager of your distro.  The table below gives package names for Debian
+and Oracle Linux.
+
+For building:
+
+| Prerequisite       | Debian                      | Oracle Linux              |
+|:-------------------|:----------------------------|:--------------------------|
+| glibc headers      | libc6-dev                   | glibc-headers             |
+| glibc (static)     | (in libc6-dev)              | glibc-static              |
+| glibc (32-bit dev) | libc6-dev-i386              | glibc-devel.i686          |
+| bison              | bison                       | bison                     |
+| flex               | flex                        | flex                      |
+| BPF gcc            | gcc-bpf                     | gcc-bpf-unknown-none      |
+| BPF binutils       | binutils-bpf                | binutils-bpf-unknown-none |
+| libpcap dev        | libpcap-dev                 | libpcap-devel             |
+| wireshark          | wireshark                   | wireshark                 |
+| valgrind           | valgrind                    | valgrind-devel            |
+| fuse3 or fuse      | libfuse3-dev or libfuse-dev | fuse3-devel or fuse-devel |
+| kernel headers     | linux-headers-<kver>-<arch> | kernel-uek-devel-<kver>   |
+|                    | linux-headers-<kver>-common |                           |
+
+At runtime:
+
+| Prerequisite       | Debian                 | Oracle Linux              |
+|:-------------------|:-----------------------|:--------------------------|
+| wireshark          | wireshark              | wireshark                 |
+| fuse3 or fuse      | libfuse3-3 or libfuse2 | fuse3-devel or fuse-devel |
+
+## 2. Build a kernel with add-on features that DTrace uses
+
+DTrace 2.0.0-1.13.1 and earlier depend on a few extra kernel features that are
+not available in the upstream kernel:
+
+- CTF type information extraction
+- /proc/kallmodsyms
+- New system call: waitfd()
+
+As noted above, patches that implement these features are available from the
+v2/* branches in our Linux kernel repository for features that DTrace uses:
+https://github.com/oracle/dtrace-linux-kernel
+
+The customary way to obtain these patches is to clone an appropriate upstream
+kernel version (5.8.1 or later) and to merge our
+[updated tree](https://github.com/oracle/dtrace-linux-kernel/tree/v2/5.8.1)
+into it.  The patch set is quite small, but may need some tweaking if it is
+being merged into a newer tree.  We occasionally push a new patched tree to our
+github repo, so do look around the repo to see if there is a branch with better
+match.
+
+Oracle Linux's [UEK7](https://github.com/oracle/linux-uek/tree/uek7/ga)
+provides a simple alternative if you don't want to patch your own kernel.
+
+Building of a patched kernel from sources is also straightforward.
+Please consult `Documentation/process/changes.rst` in the kernel source tree
+to ensure all required dependencies are installed first.  The following steps
+should build and install the kernel.
+
+```
+ Start with your preferred .config options.  Features DTrace needs should
+ enable themselves automatically.
+make olddefconfig
+make
+
+ This step will produce vmlinux.ctfa, which holds all CTF data for the kernel
+ and its modules.  If it doesn't work, you don't have a toolchain that is
+ recent enough.
+make ctf
+
+ Install with root privileges.
+sudo make INSTALL_MOD_STRIP=1 modules_install
+sudo make install
+```
+
+It is preferred (but not required) to reboot into your new kernel before
+trying to build DTrace.  (If you don't reboot into it, you need to specify
+some extra options when running make.)
+
+## 3. Build DTrace
+
+The simplest way of building DTrace is done by issuing the following commands
+from the DTrace source tree:
+
+```
+make
+sudo make install
+```
+
+Some distributions install the BPF gcc and binutils under different names.  You
+can specify the executables to use using the **BPFC** and **BPFLD** variables.
+E.g. on Debian you could use:
+
+```
+make BPFC=bpf-gcc BPFLD=bpf-ld
+sudo make install
+```
+
+In this scenario the build system expects that kernel sources can be found at
+`/lib/modules/$(uname -r)/build`.  It is also expected that the kernel used for
+userspace build is compatible with the utils (the exported userspace headers in
+the `include/uapi/linux/dtrace` are compatible with the utils version being
+built).
+
+You can point at a different kernel version with the KERNELS variable, e.g.
+```
+make KERNELS="5.16.8"
+```
+as long as the source tree that kernel was built with remains where it was
+when that kernel was installed.
+
+See `./configure --help`, `make help`, and the top-level GNUmakefile for a
+full list of options (building translators against multiple different
+kernels at once, building against kernel sources found in different places,
+building against a kernel built with O=, installing in different places,
+etc.)
+
+Some of the options (e.g., those specifying paths) may need to be specified
+when installing as well as when building.  To avoid this, you can use the
+configure script: it bakes variable settings into the makefile so that they
+persist across multiple invocations, including `make install`.
-- 
2.42.0

Re: [DTrace-devel] [PATCH] doc: updates to README

[Sam James]

[-- Attachment #1: Type: text/plain, Size: 12047 bytes --]

Kris Van Hees via DTrace-devel <dtrace-devel@oss.oracle.com> writes:

> Remove obsolete reference to kernel source and headers for building
> DTrace.
>
> Move build instructions for pre-1.13.2 versions to a new file.
>
> Signed-off-by: Kris Van Hees <kris.van.hees@oracle.com>

Thanks for doing this!

Not that it matters much for this, but maybe add:
 Link: https://github.com/oracle/dtrace-utils/issues/77

Reviewed-by: Sam James <sam@gentoo.org>

> ---
>  README.md         |  86 ++------------------------
>  README.pre-1.13.2 | 152 ++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 156 insertions(+), 82 deletions(-)
>  create mode 100644 README.pre-1.13.2
>
> diff --git a/README.md b/README.md
> index 9c506694..5855a55a 100644
> --- a/README.md
> +++ b/README.md
> @@ -128,24 +128,9 @@ make BPFC=bpf-gcc BPFLD=bpf-ld
>  sudo make install
>  ```
>  
> -In this scenario the build system expects that kernel sources can be found at
> -`/lib/modules/$(uname -r)/build`.  It is also expected that the kernel used for
> -userspace build is compatible with the utils (the exported userspace headers in
> -the `include/uapi/linux/dtrace` are compatible with the utils version being
> -built).
> -
> -You can point at a different kernel version with the KERNELS variable, e.g.
> -```
> -make KERNELS="5.16.8"
> -```
> -as long as the source tree that kernel was built with remains where it was
> -when that kernel was installed.
> -
>  See `./configure --help`, `make help`, and the top-level GNUmakefile for a
> -full list of options (building translators against multiple different
> -kernels at once, building against kernel sources found in different places,
> -building against a kernel built with O=, installing in different places,
> -etc.)
> +full list of options (installing in different places, building translators for
> +kernels, etc.)
>  
>  Some of the options (e.g., those specifying paths) may need to be specified
>  when installing as well as when building.  To avoid this, you can use the
> @@ -200,68 +185,5 @@ Support for DTrace is included in Oracle Linux support subscriptions. Individual
>  
>  ## 7. Building Previous Releases of DTrace
>  
> -For versions of DTrace prior to 2.0.0-1.13.2 a small number of kernel patches
> -patches are needed, which are
> -[here](https://github.com/oracle/dtrace-linux-kernel).  Branches named
> -starting v2/* are suitable.
> -
> -To build such versions of dtrace follow the steps below.
> -
> -### 7.1. Prerequisites
> -
> -See [above](#21-prerequisites).
> -
> -At this point, you will need an additional step:
> -
> -### 7.2. Build a kernel with add-on features that DTrace uses
> -
> -DTrace 2.0.0-1.13.1 and earlier depend on a few extra kernel features that are
> -not available in the upstream kernel:
> -
> -- CTF type information extraction
> -- /proc/kallmodsyms
> -- New system call: waitfd()
> -
> -As noted above, patches that implement these features are available from the
> -v2/* branches in our Linux kernel repository for features that DTrace uses:
> -https://github.com/oracle/dtrace-linux-kernel
> -
> -The customary way to obtain these patches is to clone an appropriate upstream
> -kernel version (5.8.1 or later) and to merge our
> -[updated tree](https://github.com/oracle/dtrace-linux-kernel/tree/v2/5.8.1)
> -into it.  The patch set is quite small, but may need some tweaking if it is
> -being merged into a newer tree.  We occasionally push a new patched tree to our
> -github repo, so do look around the repo to see if there is a branch with better
> -match.
> -
> -Oracle Linux's [UEK7](https://github.com/oracle/linux-uek/tree/uek7/ga)
> -provides a simple alternative if you don't want to patch your own kernel.
> -
> -Building of a patched kernel from sources is also straightforward.
> -Please consult `Documentation/process/changes.rst` in the kernel source tree
> -to ensure all required dependencies are installed first.  The following steps
> -should build and install the kernel.
> -
> -```
> -# Start with your preferred .config options.  Features DTrace needs should
> -# enable themselves automatically.
> -make olddefconfig
> -make
> -
> -# This step will produce vmlinux.ctfa, which holds all CTF data for the kernel
> -# and its modules.  If it doesn't work, you don't have a toolchain that is
> -# recent enough.
> -make ctf
> -
> -# Install with root privileges.
> -sudo make INSTALL_MOD_STRIP=1 modules_install
> -sudo make install
> -```
> -
> -It is preferred (but not required) to reboot into your new kernel before
> -trying to build DTrace.  (If you don't reboot into it, you need to specify
> -some extra options when running make.)
> -
> -### 7.3. Build DTrace
> -
> -See [above](#22-build-dtrace).
> +Refer to [these instructions](./README.pre-1.13.2.md) to build DTrace versions
> +prior to 2.0.0-1.13.2.
> diff --git a/README.pre-1.13.2 b/README.pre-1.13.2
> new file mode 100644
> index 00000000..1509ec65
> --- /dev/null
> +++ b/README.pre-1.13.2
> @@ -0,0 +1,152 @@
> + Linux DTrace
> +
> +For versions of DTrace prior to 2.0.0-1.13.2 a small number of kernel patches
> +patches are needed, which are
> +[here](https://github.com/oracle/dtrace-linux-kernel).  Branches named
> +starting v2/* are suitable.
> +
> +To build such versions of dtrace follow the steps below.
> +
> +## 1. Prerequisites
> +
> +Please read this section carefully before moving over to the build
> +documentation to ensure your environment is properly configured.
> +
> +### 1.1. Verify that binutils is recent enough...
> +
> +DTrace uses a type introspection system called CTF.  This is supported by
> +upstream GCC and GNU Binutils.  Make sure you have binutils 1.36 or later
> +installed.
> +
> +If your distro provides libctf.so in a binutils development package, you need
> +to install that too.
> +
> +### 1.2. or install a recent-enough binutils
> +
> +If your distro provides binutils 1.36 or later, you should install it.  If not,
> +you can build your own local copy (which can be configured with a --prefix
> +specific to itself to avoid disturbing the distro version).
> +
> +### 1.3. Install other necessary packages
> +
> +A few other packages are required, either for building or at runtime.  They
> +should be part of most Linux distributions today and can be installed via the
> +package manager of your distro.  The table below gives package names for Debian
> +and Oracle Linux.
> +
> +For building:
> +
> +| Prerequisite       | Debian                      | Oracle Linux              |
> +|:-------------------|:----------------------------|:--------------------------|
> +| glibc headers      | libc6-dev                   | glibc-headers             |
> +| glibc (static)     | (in libc6-dev)              | glibc-static              |
> +| glibc (32-bit dev) | libc6-dev-i386              | glibc-devel.i686          |
> +| bison              | bison                       | bison                     |
> +| flex               | flex                        | flex                      |
> +| BPF gcc            | gcc-bpf                     | gcc-bpf-unknown-none      |
> +| BPF binutils       | binutils-bpf                | binutils-bpf-unknown-none |
> +| libpcap dev        | libpcap-dev                 | libpcap-devel             |
> +| wireshark          | wireshark                   | wireshark                 |
> +| valgrind           | valgrind                    | valgrind-devel            |
> +| fuse3 or fuse      | libfuse3-dev or libfuse-dev | fuse3-devel or fuse-devel |
> +| kernel headers     | linux-headers-<kver>-<arch> | kernel-uek-devel-<kver>   |
> +|                    | linux-headers-<kver>-common |                           |
> +
> +At runtime:
> +
> +| Prerequisite       | Debian                 | Oracle Linux              |
> +|:-------------------|:-----------------------|:--------------------------|
> +| wireshark          | wireshark              | wireshark                 |
> +| fuse3 or fuse      | libfuse3-3 or libfuse2 | fuse3-devel or fuse-devel |
> +
> +## 2. Build a kernel with add-on features that DTrace uses
> +
> +DTrace 2.0.0-1.13.1 and earlier depend on a few extra kernel features that are
> +not available in the upstream kernel:
> +
> +- CTF type information extraction
> +- /proc/kallmodsyms
> +- New system call: waitfd()
> +
> +As noted above, patches that implement these features are available from the
> +v2/* branches in our Linux kernel repository for features that DTrace uses:
> +https://github.com/oracle/dtrace-linux-kernel
> +
> +The customary way to obtain these patches is to clone an appropriate upstream
> +kernel version (5.8.1 or later) and to merge our
> +[updated tree](https://github.com/oracle/dtrace-linux-kernel/tree/v2/5.8.1)
> +into it.  The patch set is quite small, but may need some tweaking if it is
> +being merged into a newer tree.  We occasionally push a new patched tree to our
> +github repo, so do look around the repo to see if there is a branch with better
> +match.
> +
> +Oracle Linux's [UEK7](https://github.com/oracle/linux-uek/tree/uek7/ga)
> +provides a simple alternative if you don't want to patch your own kernel.
> +
> +Building of a patched kernel from sources is also straightforward.
> +Please consult `Documentation/process/changes.rst` in the kernel source tree
> +to ensure all required dependencies are installed first.  The following steps
> +should build and install the kernel.
> +
> +```
> + Start with your preferred .config options.  Features DTrace needs should
> + enable themselves automatically.
> +make olddefconfig
> +make
> +
> + This step will produce vmlinux.ctfa, which holds all CTF data for the kernel
> + and its modules.  If it doesn't work, you don't have a toolchain that is
> + recent enough.
> +make ctf
> +
> + Install with root privileges.
> +sudo make INSTALL_MOD_STRIP=1 modules_install
> +sudo make install
> +```
> +
> +It is preferred (but not required) to reboot into your new kernel before
> +trying to build DTrace.  (If you don't reboot into it, you need to specify
> +some extra options when running make.)
> +
> +## 3. Build DTrace
> +
> +The simplest way of building DTrace is done by issuing the following commands
> +from the DTrace source tree:
> +
> +```
> +make
> +sudo make install
> +```
> +
> +Some distributions install the BPF gcc and binutils under different names.  You
> +can specify the executables to use using the **BPFC** and **BPFLD** variables.
> +E.g. on Debian you could use:
> +
> +```
> +make BPFC=bpf-gcc BPFLD=bpf-ld
> +sudo make install
> +```
> +
> +In this scenario the build system expects that kernel sources can be found at
> +`/lib/modules/$(uname -r)/build`.  It is also expected that the kernel used for
> +userspace build is compatible with the utils (the exported userspace headers in
> +the `include/uapi/linux/dtrace` are compatible with the utils version being
> +built).
> +
> +You can point at a different kernel version with the KERNELS variable, e.g.
> +```
> +make KERNELS="5.16.8"
> +```
> +as long as the source tree that kernel was built with remains where it was
> +when that kernel was installed.
> +
> +See `./configure --help`, `make help`, and the top-level GNUmakefile for a
> +full list of options (building translators against multiple different
> +kernels at once, building against kernel sources found in different places,
> +building against a kernel built with O=, installing in different places,
> +etc.)
> +
> +Some of the options (e.g., those specifying paths) may need to be specified
> +when installing as well as when building.  To avoid this, you can use the
> +configure script: it bakes variable settings into the makefile so that they
> +persist across multiple invocations, including `make install`.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 377 bytes --]