Rework of full description.

1 files changed, 72 insertions, 12 deletions

diff --git a/full-description.md b/full-description.md
index d15b8e6..5602645 100644
--- a/full-description.md
+++ b/full-description.md
@@ -1,13 +1,73 @@
-The first step in Android Open Source Project (AOSP) development is coming to terms with its peculiar build system.
-Despite being modular, AOSP's build system can be quite complex and deviate greatly from most other commonly used systems.
-Until version 7, AOSP used a Makefile based system, which in contrast to other Make based build systems, didn't rely on recursive Makefiles that find and invoke other Makefiles contained in subdirectories. Rather it used a custom script that explores all directories in the source directory in search of Android.mk files, which describe how a local module is built and handled.
-The configuration of such system also differs from others such as GNU autotools or kernel-style menuconfig, relying instead on variables that are set either as part of the shell environment or statically and ahead of time on product and device Makefiles.
-As AOSP got larger this system got slow, error prone and hard to scale and test. This Makefile-based system is in the process of being replaced by Soong which aims to add flexibility and speed by incrementally replacing the old Makefiles with Blueprint files, simpler declarative JSON-like descriptions of modules, that get translated into a Ninja manifest describing the commands that need to be run.
-During this transition the remaining Makefiles are translated to Ninja by Kati instead of being executed directly.
-Most GNU/Linux distributions use package managers, which wrap around the build system of choice of the software being packaged and bundles it into a reusable package that can be installed for direct use and or as a dependency for others. These packages can also be delivered and updated via software repositories after the initial installation of the distribution.
-In AOSP, there is no package manager, most software components have to be built from git repositories and are bundled into a single file which includes the majority of the distribution, making updating a single component harder.
-External projects, like Mesa, which are used by AOSP, cannot be built separately as they need to be built for AOSP's libc. In cases like this, Google expects the project maintainers to keep their project compatible with AOSP's build system of choice.
-While supporting Blueprint could be advantageous for Replicant, due to its faster build times, selective recompilation when source files change on disk and ability to support multiple Android versions without convoluted conditional cases, it would be preferable if Android supported some form of packages similarly to GNU/Linux distributions.
-Adding and maintaining Blueprint support in all external software components can be incredibly time consuming and could even be unsustainable.
-The Replicant project, a fork of AOSP with software freedom in mind, wishes to discuss and ultimately decide on a sustainable way to go forward in regard to external software components.
+# Android's build system isn't as cool as your distro's
+The first step in the development of an Android distribution is coming to terms
+with the Android Open Source Project (AOSP) peculiar build system. Despite
+modular, AOSP's build system is quite complex and unlike those used in most
+other distributions. For instance, it lacks the concept of packages and expects
+sub-projects to be explicitly made compatible with it.
+
+## AOSP build system internals
+Until version 7 AOSP used a Makefile based system which, in contrast to other
+Make based build systems, didn't rely on recursive Makefiles that find and
+invoke other Makefiles contained in subdirectories. Rather, it used a custom
+script that explores all subdirectories in the source directory in search of
+Android.mk files, which describe how a local module is built and handled. The
+configuration of this system also differed from others such as GNU autotools or
+kernel-style menuconfig, relying instead on variables that are set either as
+part of the shell environment or statically and ahead of time on product and
+device Makefiles.
+
+As AOSP got larger this system became slow, error prone and hard to scale and
+test. To fix this, the Makefile-based system is getting replaced by Soong. Soong
+replaces Makefiles with Blueprint files, simpler declarative JSON-like
+descriptions of modules, that get translated into a Ninja manifest describing
+the commands that need to be run. This approach takes advantage of Ninja's
+outstanding performance while sparing developers from it's complex build
+language. During the transition period the remaining Makefiles are translated
+to Ninja by Kati instead of being executed directly.
+
+The transition to Soong solved the performance issue of AOSP's builds but got
+short of taking it closer to the modularity and flexibility found in most
+GNU/Linux distributions.
+
+## Building AOSP vs building GNU/Linux distros
+Virtually all GNU/Linux distributions use package managers, which wrap around
+the build system of choice of the software being packaged and bundle it into a
+reusable package that can be installed for direct use and or as a dependency for
+others. These packages can also be delivered and updated via software
+repositories after the initial installation of the distribution. In AOSP, there
+is no package manager. Most software components are built from git repositories
+and bundled into a single image that includes the majority of the distribution.
+Updating a single component thus becomes much harder.
+
+Besides the core components of AOSP, community distributions tend to use several
+external projects like Mesa and the Linux kernel. These must usually be
+integrated into the build tree as they depend on AOSP's libc. In such cases,
+Google expects the project maintainers to keep their project compatible with
+AOSP's build system, i.e. nowadays they expect the project to have its own
+Blueprint files.
+This contrasts with GNU/Linux distributions, which provide ways to build each
+project in its own native build system and then incorporate it into the distro
+image as an independent package.
+
+## Replicant's stake
+Replicant, a fully free-software AOSP distribution, is now undergoing intense
+work to make it as sustainable as possible by sharing code with GNU/Linux
+distributions. For instance, Replicant's next release (Replicant 9) is being
+developed on top of mainline Linux and Mesa.
+
+This comes with the disadvantage of having to deal with the unsuitability of AOSP
+build system to handle external projects. Long hours of development time are
+lost due to the incapability of AOSP to detect changes in projects that haven't
+been converted to Blueprint, such as Linux, Mesa or SwiftShader.
+
+Replicant is thus seeking to discuss and ultimately decide on a sustainable way
+to go deal with external software components.
+
+Supporting Blueprint could be advantageous for Replicant, due to its faster
+build times, selective recompilation when source files change on disk and
+ability to support multiple Android versions without convoluted conditional
+cases. However it would be preferable if Android supported some form of packages
+similarly to GNU/Linux distributions.  Adding and maintaining Blueprint support
+in all external software components can be incredibly time consuming and could
+even be unsustainable.