HelloSilicon: the book's ARM64 assembly samples, ported to Apple silicon

What HelloSilicon actually is, and who it is for

HelloSilicon is a repository that follows the book Programming with 64-Bit ARM Assembly Language chapter by chapter, adjusting every sample for Apple's ARM64 machines. The README states this directly: the author codes along with the book, adjusting the sample code for Apple's ARM64 line of computers. The original source listings live in the book publisher's own repository, and HelloSilicon exists because those listings target Linux.

The audience is narrow and specific. You need Xcode 12.2 or later with the command line tools, so the tools are found in default locations such as /usr/bin. The README suggests running xcode-select --install if you are unsure. Application samples want macOS Big Sur or iOS 14, or the watchOS and tvOS equivalents. Above all, the README says that for best results you should have access to an Apple silicon Mac.

This is not a library you add to a project. The top level of the repository is a run of directories named Chapter 01 through Chapter 16, with Chapter 08 absent, plus LICENSE, README.md and an images folder. If you are looking for a package to depend on, you are in the wrong repository.

Why the book's listings do not assemble on macOS unchanged

Two platforms diverge at exactly the level this material operates on: system calls and memory access. Linux and Darwin both descend from AT&T Unix System V, but the calling details differ, and the README organizes the whole document around that gap so you can read the book and the differences side by side.

The assembler itself is the first obstacle. The book uses Linux GNU tools, including the GNU as assembler. On macOS there is an as command, but it invokes the integrated LLVM Clang assembler by default. The -Q option that would select the GNU-based assembler was only ever available for x86_64 and is deprecated. The README shows the failure:

% as -Q -arch arm64
/usr/bin/as: can't specifiy -Q with -arch arm64

So GNU assembler syntax is not an option and the code must be adjusted for Clang assembler syntax. The same substitution applies to the compiler: there is a gcc command on macOS, but it calls Clang, so the README replaces every gcc invocation with clang for transparency. Expect to rewrite directives and operand forms as you go, not just recompile.

Alignment is a smaller but real adjustment. The README inserts .align 4, or equivalently .p2align 2, to silence a warning, because Darwin wants things aligned on even boundaries. Apple also reserves register X18 for platform use and says not to use it, and the frame pointer register (FP, X29) must always address a valid frame record.

The Darwin system call convention, and why the README cautions you

This is the substance of the port. Three things change between Linux and macOS when you ask the kernel to do something.

The function number goes in a different register. Linux places it on X8; macOS places it on X16. The numbers themselves differ too: the README gives the example of Linux using 64 where macOS uses 4. The authoritative table it points to is syscalls.master in Apple's open source xnu distribution.

The interrupt instruction differs. On Linux the call is 0; on Apple silicon it is 0x80.

Before you build anything on those numbers, read the caution the README attaches to the syscall table: Darwin function numbers are considered private by Apple and are subject to change, and they are provided here for educational purposes only. That is an honest framing and it should shape how you use this repository. Syscall numbers are not a stable interface, so sample code that hardcodes them is teaching material, not production code. If you port a listing into something you intend to ship, the syscall layer is the part most likely to break under you.

Building Hello World with the Darwin linker

The README's Hello World walkthrough is the fastest way to confirm your toolchain before you work through the chapters. The linker call it gives is:

ld -o HelloWorld HelloWorld.o \
	-lSystem \
	-syslibroot `xcrun -sdk macosx --show-sdk-path` \
	-e _start \
	-arch arm64

Each switch has a purpose. -o names the output, as usual. -lSystem links the executable against libSystem.dylib, which adds the LC_MAIN load command. -syslibroot points at the SDK path that xcrun reports. -e _start sets the entry point symbol, and -arch arm64 selects the architecture. If xcrun is not on your path, the command substitution fails and the link will not find the SDK, so check xcode-select first.

The README notes that Darwin generally does not support statically linked executables, which is why libSystem is in the command at all. It mentions that building without libSystem.dylib is possible but not especially elegant, and says it will go deeper into that topic when time permits. Treat that as an acknowledged gap rather than a documented path.

The README also says these changes need to be applied to the makefile and to the build file, which tells you the samples are not all driven by one top-level build. Before relying on a chapter, look inside its directory for the makefile rather than assuming a repository-wide build command exists.

What the repository does not cover

The README does not document rollback, versioning of the samples, or a compatibility matrix across Xcode releases. The most recent release listed is 1.3 from 2022-03-17, labelled macOS 12.3 Release, following 1.2 in October 2021 and 1.1 in December 2020. The repository itself was last pushed on 2026-05-15, so work has continued past the last tagged release, but the README gives no changelog that maps tags to chapter content.

The port is also deliberately incomplete in scope. The README says the book is based on Linux with the exception of the existing iOS samples, and that while all samples can be adjusted to work on the iPhone and other Apple ARM64 devices, an Apple silicon Mac gives the best results. That is a soft boundary. You will spend time adapting listings for anything other than a Mac, and the README does not catalog which samples need what.

Finally, the syscall caution cuts both ways. Because Darwin function numbers are private and subject to change, a listing that worked when written may not work on a later OS. Nothing in the README promises otherwise.

How it compares with the book's own source repository

The obvious alternative is the original code from Apress, which the README links as the source of the samples. The difference in approach is the target platform. The Apress repository holds the listings as the book presents them, aimed at Linux GNU tools. HelloSilicon holds the same listings rewritten for the Clang assembler, the Darwin linker and the Apple silicon syscall convention, with the README explaining each divergence as it appears.

That means the two are not interchangeable. If you are working through the book on a Linux machine, the original repository is the correct match and HelloSilicon's changes will get in your way. If you are on an Apple silicon Mac, the original listings will not assemble as written, and HelloSilicon is the version that accounts for the -Q limitation, the X16 register, the 0x80 interrupt and the libSystem link step.

A second alternative is simply to read Apple's own documentation and the xnu syscall table without a book. That gives you the current numbers but not the chapter-by-chapter progression, which is the thing this repository is organized around.

Licence and the cost of keeping up

HelloSilicon is MIT licensed, and the LICENSE file sits at the top level of the repository alongside README.md. That is permissive and places few obligations on reuse of the sample code, but it is worth being precise about what the licence does not cover: the repository is a companion to a commercial book, and the listings are adaptations of that book's material. The MIT grant applies to what is in this repository. Whether your use of derived listings from the book requires anything further is a question for the book's own terms, not this licence. That is not legal advice, and if the distinction matters to your situation, read both.

The maintenance cost is the Darwin syscall table. Every sample that makes a system call depends on numbers the README itself flags as private and subject to change. When Apple adjusts them, the samples that use them need to be revisited. The README's caution is the honest statement of that exposure, and it is the reason to treat this repository as a learning resource rather than a base to build on.

Editorial conclusion

Adopt HelloSilicon if you already own or are reading the book and want its Listings to assemble and link on an Apple silicon Mac, or if you need a worked reference for the Darwin syscall convention. Do not adopt it as a standalone tutorial or as a build system for a real assembly project: it is a companion repository whose structure mirrors book chapters. Verify first that Xcode 12.2 or later is installed with the command line tools, and confirm that the chapter directory you need contains a makefile before assuming the samples build with a single command.

Frequently asked questions

Official sources

1. below/HelloSilicon on GitHub
2. Issues
3. License: MIT
4. README
5. Releases