Skip to content

Update README #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 26, 2024
Merged

Update README #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 11 additions & 87 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,6 @@ Source code for the UEK kernel is available on github in the
* [5. Questions](#5-questions)
* [6. Pull Requests and Support](#6-pull-requests-and-support)
* [7. Building Previous Releases of DTrace](#7-building-previous-releases-of-dtrace)
* [7.1. Prerequisites](#71-prerequisites)
* [7.2. Build a kernel with add-on features that DTrace uses](#72-build-a-kernel-with-add-on-features-that-dtrace-uses)
* [7.3. Build DTrace](#73-build-dtrace)

## 1. License

Expand Down Expand Up @@ -121,31 +118,21 @@ 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 would use:
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).
See `./configure --help`, `make help`, and the top-level GNUmakefile for a
full list of options (installing in different places, building translators for
kernels, etc.)

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 the GNUmakefile for more options (building translators against multiple
different kernels at once, building against kernel sources found in
different places, building against a kernel built with O=, etc.)

'make help' might also be of interest.
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`.

## 3. Testing

Expand Down Expand Up @@ -181,7 +168,7 @@ which is installed in /usr/**bin**/dtrace.

For questions, please ask on the [dtrace mailing list](https://lore.kernel.org/dtrace/).
Older discussions are archived [here](https://oss.oracle.com/pipermail/dtrace-devel/).

We have a #linux-dtrace IRC channel on irc.libera.chat, you can
ask questions there as well.

Expand All @@ -195,68 +182,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.
152 changes: 152 additions & 0 deletions README.pre-1.13.2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.