# Building AltOS
The AltOS source tree has a fairly long list of build dependencies, because
-it builds firmware for at least 4 different processor cores, ground station
-software in Java, various utilities in C, etc. By *far* the easiest way to
-build from source is to start with a [Debian](http://debian.org) 'unstable'
-installation and take advantage of Debian tools and processes. From this
-platform, it is possible to build installable packages not only for Debian,
+it builds firmware for a number of different processor cores, ground station
+software in Java, various utilities in C, documentation, etc. Because Bdale
+and Keith are both [Debian GNU/Linux](https://debian.org) developers, by far
+the easiest way to build from source is to start with a
+Debian 'unstable' installation and take advantage of
+Debian tools and processes. From this platform, it is possible to build
+installable packages not only for Debian,
but also for Windows, Mac OS X, and generic Linux.
+Since many people would prefer to work from an actually released version of
+Debian, in October 2020 Bdale worked through the steps required to take a
+clean install of Debian 10 (buster) and get to a working build. Here's that
+recipe, as sent to a customer who asked how to do it:
+
+<pre>
+ I actually had to install a fresh buster instance in a VM so that I
+ could chase this down. And then there was an "of course!" moment.
+
+ The complication is based on the fact that Keith and I both run Debian
+ 'unstable', aka 'sid', all the time since we're Debian developers. And
+ it turns out that to build our master branch, you need an ARM cross tool
+ chain that's just newer than what's in buster. Fortunately, that can be
+ installed without perturbing the rest of the system much.
+
+ I took serious notes on how to go from nothing to a working build on
+ buster, here's the recipe:
+
+ # make sure we're on latest buster
+ apt update && apt upgrade
+
+ # set up build dependencies, etc .. the json lib is a new build dep
+ # since buster, so install it manually as 'apt build-dep' won't
+ apt install build-essential git libjson-c-dev
+ apt build-dep altos
+
+ # move from newlib to picolibc, requires updating cross compiler too
+ dpkg --purge libnewlib-nano-arm-none-eabi
+
+ - to get latest ARM cross toolchain, temporarily add to
+ /etc/apt/sources.list a line like:
+
+ deb http://deb.debian.org/debian/ sid main
+
+ apt update
+
+ # this pulls in the latest compiler, runtime library, and dependencies
+ # like gcc-10-base and two related libraries
+ apt install gcc-arm-none-eabi picolibc-arm-none-eabi
+
+ - probably safest to now comment out the sid line in sources.list, and
+ make sure the packaging system forgets about sid for now with
+ apt update
+
+ git clone git://git.gag.com/fw/altos
+ cd altos
+ git checkout master
+ ./autogen.sh
+ make
+
+ That happily ran to completion for me.
+
+ Hope this helps!
+</pre>
+
Install [Debian](http://debian.org), then type 'apt-get build-dep altos'
and all of the required build dependencies should be automatically installed.
The notes we use to do a complete build for release are in the file
-Releasing in the root of the source tree. Not all of those details are
-necessary unless you're trying to do an official release, but all the info
-necessary to rebuild from source is captured there.
+Releasing in the root of the source tree. You do *not* need to follow these
+instructions to do a build for yourself, but since that document is likely
+to be kept up to date better than this one, feel free to check there for
+hints on things that might have changed, and/or feel free to reach out to
+us for help if you get stuck.
If you really want to try and build our source tree on a development platform
other than Debian, feel free... just don't expect us to help! It's hard
projects / web / altusmetrum / blobdiff