Building a linux kernel on a Linux OS is easy and straightforward. You can easily follow the installation instructions provided in the documentation. If you are a Windows user, you can use Windows Subsytem for Linux (WSL) to setup the development environment. For MacOS users (especially on Mac M1), setting your development environment for building linux kernel can be very frustrating (at least that's my experience).

Since I have spent considerable amount of time trying, failing, trying again, and finally succeed, I am going to document what I have tried, the issues I encountered and how I solve those issues in this post.

Background

At this moment I am learning about linux kernel and device driver development. For this purpose, I would like to build linux kernel for BeagleBone Black board and run this kernel on this device.

Building Linux Kernel

1. Download source code

Clone the linux kernel repository.

$ git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux
$ cd linux

Add the stable remote to access the stable versions

$ git remote add stable https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable
$ git fetch stable

You should be able to list all branches on the stable tree. Checkout a specific linux kernel version.

$ git branch -a

# Checkout linux kernel v5.10
git checkout -b 5.10.bootlin stable/linux-5.10.y

2. Setup cross-compiling toolchain

Install the toolchain using brew.

$ brew install gcc-arm-embedded --cask
$ brew install cmake autoconf libtool gcc automake openssl
$ brew link openssl --force

3. Setup the configuration

$ make menuconfig

You can set the configurations however you want. In my case, I set the following configurations:

• CONFIG_USB_GADGET = y
• CONFIG_USB_MUSB_HDRC = y
• CONFIG_USB_MUSB_GADGET = y
• CONFIG_USB_MSUB_DSPS = y
• CONFIG_AM335X_PHY_USB = y
• CONFIG_USB_ETH = y
• CONFIG_ROOT_NFS = y
• CONFIG_KERNEL_LZO = y

4. Build

$ export ARCH="arm"
$ export CROSS_COMPILE="arm-none-eabi-"

# Build using 8 cores (Change accordingly)
$ make -j 8

During the building process, some errors will occur. Check the next section on how to solve those errors.

Known Issues

Problems that I encountered while setting up the dev environment.

elf.h: no such file or directory

This file does not exist on MacOs. The fix itself is quick easy. First get the file from https://gist.github.com/mlafeldt/3885346.

# Create the file using any file editor. 
# Then copy paste the content from the URL above and save it.

$ nano /usr/local/include/elf.h

openssl/bio.h: no such file or directory

During the compilation process, the tool cannot find this header file from /usr/local/include. You have to install openssl using brew.

$ brew install openssl

# Add the following environment variables
$ export CPATH=/opt/homebrew/include
$ export LIBRARY_PATH=/opt/homebrew/lib

# Run make and this error will be gone.

typedef redefinition with different types struct uuid_t vs __darwin_uuid_t

Depending on the version of the linux kernel you are building, you will or will not encounter this issue. The version that I am using is v5.10.

In order to solve this issue, you have to modify this file <src>/scripts/mod/file2alias.c. Check the code snippet below and add those new three lines.

// Find the following code snippet in the original file (i.e. line 45)

/* backwards compatibility, don't use in new code */
typedef struct {
    __u8 b[16];
} uuid_le;

// Change the shell of the uuid_t structure through the macro definition before it is defined #ifdef __APPLE__
    #define uuid_t compat_uuid_t
#endif

typedef struct {
        __u8 b[16];
} uuid_t;

lzop

If you enable LZOP kernel compression method, you will encounter this issue. You can solve it by installing lzop using brew.

$ brew install lzop

Conclusion

That's it for the steps I did to setup my development environment for building linux kernel on MacOS M1. Hopefully it is helpful to you as it will be for my future self in case I need to setup my dev environment again.