Build system setup macOS

This is an old revision of the document!

This method is NOT OFFICIALLY supported. A native GNU/Linux environment is recommended.

Tested with macOS 10.15.7, Xcode 12.1 build 12A7403, & packages from homebrew.
Tested with macOS 11.6, Xcode 13.0 build 13A233, arm64 kernel, & packages from homebrew.

A. Obtain build toolchain that is more suitable for Apple hardware:

Install Xcode or CLT:
1. Obtain Xcode¹ from here. Note: installer file download is over/near 5 GB, and needs 17+ GB space. Xcode 11.5 : 16,958,217,326 bytes (10.5 GB on disk).
2. If you prefer to not obtain Xcode, then one of the alternative is:
  - obtain Command-Line-Tools¹ (CLT) from here, or Load it from App Store in macOS, or use below command, or obtain apple-gcc package via package manager software. CLT is also known as Command Line Developer Tools. Note: installer download is under/near 300 MB, and may need around ~ 2 GB space.
  - inside Terminal¹ utility/app, run this command to load CLT:
```
xcode-select --install
```
Build toolchain from apple is used (in first stage) to create a software components for openwrt build purpose, then (in second stage) those software components are used to create the final openwrt components, in order to create openwrt firmware, etc, that are widely compatible with cross-platform.

B. Unhide hidden files/folders in macOS:

We need to view full filename, file extensions, all files & directories, etc including hidden ones, very accurately, so that there is lesser mistakes.
Use Finder to start Terminal in macOS:
- Finder is very similar to Windows-Explorer file-browser app/tool. In macOS > click on any empty area in Desktop screen > in top-side menu click on Window > click on Bring All to Front > in left-pane (in left side column) of Finder, go under Favorites and click on the Applications > then scroll down & go into Utilities sub-folder > then click on Terminal or Terminal.app to start it. macOS Terminal is very similar to Windows Command-Prompt, a command-line interface (CLI) tool.
- Hotkeys to start Finder instantly : [Alt/Option⌥] + [Command⌘] + [Space-bar] then close the Search tab.
- Hotkeys to start Terminal instantly : None. ( Note: Keep Terminal running, after a reboot Terminal will auto-start if you check-marked the option: Load previous running apps after reboot ).

Run below command inside Terminal:

defaults write com.apple.Finder AppleShowAllFiles true

then you must reboot Mac-computer OR run (any one of the) below command:

/usr/bin/sudo /usr/bin/killall Finder /System/Library/CoreServices/Finder.app

or, run just this:

/usr/bin/sudo /usr/bin/killall Finder

or, just this:

sudo killall Finder

then Finder will auto start, and all hidden files+folders will by-default begin to be shown to user in macOS Finder.
in macOS Finder or inside any other file browsing window in macOS, user can also press below THREE buttons altogether ONCE to show all HIDDEN files/folders:
- [Command⌘] + [Shift⇧] + [.>]
- if user press-es above three buttons again, file-browsing-window will HIDE the HIDDEN files/folders.
By default in macOS, Finder will keep most of the file extension hidden. But we need to see all file's extension to see FULL filename, so we can be sure & not make mistake. To view all file's extension, do below steps:
- in macOS > start “Finder” app > goto main menu > Finder > Preferences > Advanced > select the Show All Filename Extensions option.

C. Install any one of the (3rd-party) package manager (pkg-mngr) software in macOS:

Homebrew : Note: it shares user's usage/private data with Ggl.
MacPorts¹.

D. Prepare a dedicated case-sensitive filesystem for OpenWRT build/compile purpose, in Terminal:

We will be using a sparsebundle to allow us to have a case sensitive filesystem.

The size that you provide will be the max size of the volume for working with OpenWrt:

cd ~
hdiutil create -size 20g -type SPARSE -fs "Case-sensitive HFS+" -volname OpenWrt OpenWrt.sparseimage
hdiutil attach OpenWrt.sparseimage

Optional/Informational:
- if you want to open the OpenWRT Volume (aka: Drive, aka: Disk) after creating then use below command as 3rd-command line in above:
```
hdiutil attach OpenWrt.sparseimage -autoopenrw
```
- after a reboot, if OpenWRT volume is not available in your macOS, then run:
```
cd ~ && hdiutil attach OpenWrt.sparseimage -autoopenrw
```
- if you want to keep the OpenWRT volume always attached, then:
```
cd ~ && sudo hdiutil attach OpenWrt.sparseimage -notremovable -autoopenrw
```
- if you want to detach (aka: unmount) the OpenWRT volume, then:
```
hdiutil detach /Volumes/OpenWrt
```
- More info on hdiutil is here.

E. Go into OpenWRT build volume, with this command, in Terminal:

```
cd /Volumes/OpenWrt
```

F. Install necessary packages with below command(s), in Terminal:
Note: Packages will be installed inside macOS default volume, not inside /Volumes/OpenWrt

if you have homebrew then run this:

brew install coreutils findutils gawk grep gnu-getopt gnu-tar wget diffutils git-extras quilt svn make ncurses pkg-config

in above homebrew does not include the pre-requisites (aka: dependencies) packages mentioned here.

if you have MacPorts then run this:

sudo port install libiconv gettext-runtime coreutils findutils gwhich gawk zlib pcre bzip2 ncurses grep getopt gettext-tools-libs gettext diffutils sharutils util-linux libxslt libxml2 help2man readline gtime gnutar unzip zip lzma xz libelf fastjar libusb libftdi0 expat sqlite3 openssl3 openssl kerberos5 dbus lz4 libunistring nettle icu gnutls p11-kit wget quilt subversion gmake pkgconfig libzip cdrtools ccache curl xxhashlib rsync libidn perl5 p5.28-xml-parser p5.30-xml-parser p5-extutils-makemaker p5-data-dumper boost-jam boost boost-build bash bash-completion binutils m4 flex intltool patchutils swig git-extras git openjdk17 openjdk7-zulu luajit libtool glib2 file python27 python310 libzzip mercurial asciidoc sdcc gnu-classpath

in above MacPorts includes the pre-requisites (aka: dependencies) packages mentioned here. Space initially used by all of these packages : 4,190,442,792 bytes (2.57 GB on disk) for 129,623 items, (as of March-11, 2022). Note: As different packages are continuously modified & improved by their devs or releaser or adopter or maintainer, so their occupying space size & items count will be different in your computer in different time.
if you need picocom tool to communicate with router via serial cable connection, then:
```
sudo port install picocom
```
if you need last stable openssh (aka: ssh), sftp, scp tools for secure communication or file-transfer, then:
```
sudo port install openssh
```
if you need last stable telnet, ftp, rsh, rlogin, tftp tools and corresponding daemons, then:
```
sudo port install inetutils
```
- if you need other type of bundled packages, then look here: 1.

if you need these type of tools, (more info: 1), then:

sudo port install arm-elf-binutils i386-elf-binutils m68k-elf-binutils mips-elf-binutils x86_64-elf-binutils

G. Optional-step : Start a build/compile friendly common shell inside a specific Terminal tab:
We need+should use last stable version of bash shell, as it can be obtained & used by most devs/users. Terminal can run multiple shell(s), so it can have multiple Terminal-tabs. Select one (or more) Terminal-tab(s) to use for openwrt build purpose, then run below command to have same build environment.

If you installed new bash package, then start new bash shell inside a specific tab in Terminal, (when you have MacPorts based bash package), with this command:
```
exec /opt/local/bin/bash
```
- optional : approve/permit new bash shell in macOS: echo “/opt/local/bin/bash” | sudo tee -a /private/etc/shells
- optional : if you want to continue to use the new bash always, then: click on apple  symbol in topside apple menu-bar > System Preferences... > Users & Groups > Unlock the 🔒pane > control click on your user-name > select Advanced Options... > then update/change the Login shell into /opt/local/bin/bash > ok.

H. Create build package location indicator file:

Create a file called env.sh inside /Volumes/OpenWrt to indicate location of installed packages.
- This is to allow the utilities (aka: packages) we just installed to be used, instead of the macOS provided ones.

For x86_64 Apple hardware, & when you have homebrew, then create env.sh file with below content:

PATH="/usr/local/opt/make/libexec/gnubin:$PATH"
PATH="/usr/local/opt/gnu-getopt/bin:$PATH"
PATH="/usr/local/opt/gettext/bin:$PATH"
PATH="/usr/local/opt/coreutils/libexec/gnubin:$PATH"
PATH="/usr/local/opt/findutils/libexec/gnubin:$PATH"
export PATH

For x86_64 Apple hardware, & when you have MacPorts, then create env.sh file with below content:

env.sh

#!/opt/local/bin/bash
PATH="/opt/local/libexec/gnubin:$PATH"
PATH="/opt/local/bin:$PATH"
PATH="/opt/local/sbin:$PATH"
PATH="/opt/local/x86_64-apple-darwin19.6.0/bin:$PATH"
export PATH
export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk7-zulu/Contents/Home

For arm64 (Apple Silicon(M1)) Apple hardware, & when you have homebrew, then create env.sh file with below content:

PATH="/opt/homebrew/opt/make/libexec/gnubin:$PATH"
PATH="/opt/homebrew/opt/gnu-getopt/bin:$PATH"
PATH="/opt/homebrew/opt/gettext/bin:$PATH"
PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH"
PATH="/opt/homebrew/opt/findutils/libexec/gnubin:$PATH"
export PATH

Optional : you may check homebrew official page or MacPorts-guide if you need more information related to PATH variable, or other info on pkg-mngr.
Optional : turn env.sh file an executable shell script file: chmod +x /Volumes/OpenWrt/env.sh

I. Load build package location indicator file as shell environment:
OpenWRT developing (aka: building, aka: compiling, aka: compilation) is done inside a suitable shell environment. So, we have to allow openwrt build commands to find packages that we installed via pkg-mngr, by loading build package location indicator file env.sh into one of the Terminal shell environment tab, to create that openwrt build friendly & suitable shell environment.

When developing (aka: building, aka: compiling), run below command to set up the path (and other) variable(s). This leaves your system in a clean state without symlinking.
```
source /Volumes/OpenWrt/env.sh
```
- Optional : So from next time or after a reboot, when you want to enter into openwrt build mode into a specific tab in Terminal, then run below 2 commands, when you have MacPorts based bash package:
```
exec /opt/local/bin/bash
source /Volumes/OpenWrt/env.sh
```

J. Now proceed normally.

Users who are developing openwrt firmware for Broadcom (BCM) 43xx chipset, need this b43-fwcutter tool to extract wireless drivers from firmware.

More info here.
Package manager homebrew has this tool, and MacPorts does not.
- Users of MacPorts can obtain source^{1, 2, 3, 4} & compile, or get it¹ from FreeBSD pkg.

Golang¹: For darwin/arm64 and linux/aarch64 golang package (feed “packages”) golang C-bootstrap method doesn't work, but it is possible to use external golang bootstrap. On MacOS arm64 the easiest way is to install golang using brew and use installed golang as bootstrap:

```
brew install golang
```
Then set CONFIG_GOLANG_EXTERNAL_BOOTSTRAP_ROOT=“/opt/homebrew/opt/go/libexec” in .config file

Build system setup macOS

B43-FWCutter

Golang related