1# Quick Start Recipes 2 3## Checking out the Zircon source code 4 5*** note 6NOTE: The Fuchsia source includes Zircon. See Fuchsia's 7[Getting Started](https://fuchsia.googlesource.com/docs/+/master/getting_started.md) 8doc. Follow this doc to work on only Zircon. 9*** 10 11The Zircon Git repository is located 12at: https://fuchsia.googlesource.com/zircon 13 14To clone the repository, assuming you setup the $SRC variable 15in your environment: 16```shell 17git clone https://fuchsia.googlesource.com/zircon $SRC/zircon 18``` 19 20For the purpose of this document, we will assume that Zircon is checked 21out in $SRC/zircon and that we will build toolchains, QEMU, etc alongside 22that. Various make invocations are presented with a "-j32" option for 23parallel make. If that's excessive for the machine you're building on, 24try -j16 or -j8. 25 26## Preparing the build environment 27 28### Ubuntu 29 30On Ubuntu this should obtain the necessary pre-reqs: 31``` 32sudo apt-get install texinfo libglib2.0-dev autoconf libtool bison libsdl-dev build-essential 33``` 34 35### macOS 36Install the Xcode Command Line Tools: 37``` 38xcode-select --install 39``` 40 41Install the other pre-reqs: 42 43* Using Homebrew: 44``` 45brew install wget pkg-config glib autoconf automake libtool 46``` 47 48* Using MacPorts: 49``` 50port install autoconf automake libtool libpixman pkgconfig glib2 51``` 52 53## Install Toolchains 54 55If you're developing on Linux or macOS, there are prebuilt toolchain binaries available. 56Just run this script from your Zircon working directory: 57 58``` 59./scripts/download-prebuilt 60``` 61 62If you would like to build the toolchains yourself, follow the instructions later 63in the document. 64 65## Build Zircon 66 67Build results will be in $SRC/zircon/build-{arm64,x64} 68 69The variable $BUILDDIR in examples below refers to the build output directory 70for the particular build in question. 71 72``` 73cd $SRC/zircon 74 75# for aarch64 76make -j32 arm64 77 78# for x64 79make -j32 x64 80``` 81 82### Using Clang 83 84To build Zircon using Clang as the target toolchain, set the 85`USE_CLANG=true` variable when invoking Make. 86 87``` 88cd $SRC/zircon 89 90# for aarch64 91make -j32 USE_CLANG=true arm64 92 93# for x64 94make -j32 USE_CLANG=true x64 95``` 96 97## Building Zircon for all targets 98 99``` 100# The -r enables release builds as well 101./scripts/buildall -r 102``` 103 104Please build for all targets before submitting to ensure builds work 105on all architectures. 106 107## QEMU 108 109You can skip this if you're only testing on actual hardware, but the emulator 110is handy for quick local tests and generally worth having around. 111 112See [QEMU](qemu.md) for information on building and using QEMU with zircon. 113 114 115## Build Toolchains (Optional) 116 117If the prebuilt toolchain binaries do not work for you, you can build your 118own from vanilla upstream sources. 119 120 * The GCC toolchain is used to build Zircon by default. 121 * The Clang toolchain is used to build Zircon if you build with 122 `USE_CLANG=true` or `USE_ASAN=true`. 123 * The Clang toolchain is also used by default to build host-side code, but 124 any C++14-capable toolchain for your build host should work fine. 125 126Build one or the other or both, as needed for how you want build Zircon. 127 128### GCC Toolchain 129 130We use GNU `binutils` 2.30(`*`) and GCC 8.2(`**`), configured with 131`--enable-initfini-array --enable-gold`, and with `--target=x86_64-elf 132--enable-targets=x86_64-pep` for x86-64 or `--target=aarch64-elf` for ARM64. 133 134For `binutils`, we recommend `--enable-deterministic-archives` but that switch 135is not necessary to get a working build. 136 137For GCC, it's necessary to pass `MAKEOVERRIDES=USE_GCC_STDINT=provide` on the 138`make` command line. This should ensure that the `stdint.h` GCC installs is 139one that works standalone (`stdint-gcc.h` in the source) rather than one that 140uses `#include_next` and expects another `stdint.h` file installed elsewhere. 141 142Only the C and C++ language support is required and no target libraries other 143than `libgcc` are required, so you can use various `configure` switches to 144disable other things and make your build of GCC itself go more quickly and use 145less storage, e.g. `--enable-languages=c,c++ --disable-libstdcxx 146--disable-libssp --disable-libquadmath`. See the GCC installation 147documentation for more details. 148 149You may need various other `configure` switches or other prerequisites to 150build on your particular host system. See the GNU documentation. 151 152(`*`) The `binutils` 2.30 release has some harmless `make check` failures in 153the `aarch64-elf` and `x86_64-elf` configurations. These are fixed on the 154upstream `binutils-2_30-branch` git branch, which is what we actually build. 155But the 2.30 release version works fine for building Zircon; it just has some 156spurious failures in its own test suite. 157 158(`**`) As of 2008-6-15, GCC 8.2 has not been released yet. There is no 159released version of GCC that works for building Zircon without backporting 160some fixes. What we actually use is the upstream `gcc-8-branch` git branch. 161 162### Clang/LLVM Toolchain 163 164We use a trunk snapshot of Clang and update to new snapshots frequently. Any 165build of recent-enough Clang with support for `x86_64` and `aarch64` compiled 166in should work. You'll need a toolchain that also includes the runtime 167libraries. We normally also use the same build of Clang for the host as well 168as for the `*-fuchsia` targets. See 169[here](https://fuchsia.googlesource.com/docs/+/master/development/build/toolchain.md) 170for details on how we build Clang. 171 172### Set up `local.mk` for toolchains 173 174If you're using the prebuilt toolchains, you can skip this step, since 175the build will find them automatically. 176 177Create a GNU makefile fragment in `local.mk` that points to where you 178installed the toolchains: 179 180```makefile 181CLANG_TOOLCHAIN_PREFIX := .../clang-install/bin/ 182ARCH_x86_64_TOOLCHAIN_PREFIX := .../gnu-install/bin/x86_64-elf- 183ARCH_arm64_TOOLCHAIN_PREFIX := .../gnu-install/bin/aarch64-elf- 184``` 185 186Note that `CLANG_TOOLCHAIN_PREFIX` should have a trailing slash, and the 187`ARCH_*_TOOLCHAIN_PREFIX` variables for the GNU toolchains should include the 188`${target_alias}-` prefix, so that simple command names like `gcc`, `ld`, or 189`clang` can be appended to the prefix with no separator. If the `clang` or 190`gcc` in your `PATH` works for Zircon, you can just use empty prefixes. 191 192## Copying files to and from Zircon 193 194With local link IPv6 configured, the host tool ./build-ARCH/tools/netcp 195can be used to copy files. 196 197``` 198# Copy the file myprogram to Zircon 199netcp myprogram :/tmp/myprogram 200 201# Copy the file myprogram back to the host 202netcp :/tmp/myprogram myprogram 203``` 204 205## Including Additional Userspace Files 206 207The Zircon build creates a bootfs image containing necessary userspace components 208for the system to boot (the device manager, some device drivers, etc). The kernel 209is capable of including a second bootfs image which is provided by QEMU or the 210bootloader as a ramdisk image. 211 212To create such a bootfs image, use the zbi tool that's generated as part of 213the build. It can assemble a bootfs image for either source directories (in which 214case every file in the specified directory and its subdirectories are included) or 215via a manifest file which specifies on a file-by-file basis which files to include. 216 217``` 218$BUILDDIR/tools/zbi -o extra.bootfs @/path/to/directory 219 220echo "issue.txt=/etc/issue" > manifest 221echo "etc/hosts=/etc/hosts" >> manifest 222$BUILDDIR/tools/zbi -o extra.bootfs manifest 223``` 224 225On the booted Zircon system, the files in the bootfs will appear under /boot, so 226in the above manifest example, the "hosts" file would appear at /boot/etc/hosts. 227 228For QEMU, use the -x option to the run-zircon-* scripts to specify an extra bootfs image. 229 230## Network Booting 231 232Network booting is supported via two mechanisms: Gigaboot and Zirconboot. 233Gigaboot is an EFI based bootloader whereas zirconboot is a mechanism that 234allows a minimal zircon system to serve as a bootloader for zircon. 235 236On systems that boot via EFI (such as Acer and NUC), either option is viable. 237On other systems, zirconboot may be the only option for network booting. 238 239### Via Gigaboot 240The [GigaBoot20x6](https://fuchsia.googlesource.com/zircon/+/master/bootloader) bootloader speaks a simple network boot protocol (over IPV6 UDP) 241which does not require any special host configuration or privileged access to use. 242 243It does this by taking advantage of IPV6 Link Local Addressing and Multicast, 244allowing the device being booted to advertise its bootability and the host to find 245it and send a system image to it. 246 247If you have a device (for example a Broadwell or Skylake Intel NUC) running 248GigaBoot20x6 first create a USB drive [manually](https://fuchsia.googlesource.com/zircon/+/master/docs/targets/acer12.md#How-to-Create-a-Bootable-USB-Flash-Drive) 249or (Linux only) using the [script](https://fuchsia.googlesource.com/scripts/+/master/build-bootable-usb-gigaboot.sh). 250 251``` 252$BUILDDIR/tools/bootserver $BUILDDIR/zircon.bin 253 254# if you have an extra bootfs image (see above): 255$BUILDDIR/tools/bootserver $BUILDDIR/zircon.bin /path/to/extra.bootfs 256``` 257 258By default bootserver will continue to run and every time it observes a netboot 259beacon it will send the kernel (and bootfs if provided) to that device. If you 260pass the -1 option, bootserver will exit after a successful boot instead. 261 262 263### Via Zirconboot 264Zirconboot is a mechanism that allows a zircon system to serve as the 265bootloader for zircon itself. Zirconboot speaks the same boot protocol as 266Gigaboot described above. 267 268To use zirconboot, pass the `netsvc.netboot=true` argument to zircon via the 269kernel command line. When zirconboot starts, it will attempt to fetch and boot 270into a zircon system from a bootserver running on the attached host. 271 272## Network Log Viewing 273 274The default build of Zircon includes a network log service that multicasts the 275system log over the link local IPv6 UDP. Please note that this is a quick hack 276and the protocol will certainly change at some point. 277 278For now, if you're running Zircon on QEMU with the -N flag or running on hardware 279with a supported ethernet interface (ASIX USB Dongle or Intel Ethernet on NUC), 280the loglistener tool will observe logs broadcast over the local link: 281 282``` 283$BUILDDIR/tools/loglistener 284``` 285 286## Debugging 287 288For random tips on debugging in the zircon environment see 289[debugging](debugging/tips.md). 290 291## Contribute changes 292* See [contributing.md](contributing.md). 293