Clean up BUILDCONFIG.gn

Starting a new project requires copying Pigweed's BUILDCONFIG.gn as the
foundation for a project's own BUILDCONFIG. This change adds
documentation and some minor changes to the structure of the BUILDCONFIG
to simplify it.

Change-Id: I1354afedea28b1d1e04d1cdb663451f73c6fc3f9

BUILDCONFIG.gn

@@ -12,31 +12,21 @@
 # License for the specific language governing permissions and limitations under
 # the License.
 
-import("modules.gni")
-
-# Default configs to use for all binary build targets.
-_default_common_binary_configs = [
-  "$dir_pw_build:reduced_size",
-  "$dir_pw_build:strict_warnings",
-]
-
-set_defaults("executable") {
-  configs = _default_common_binary_configs
-}
-
-set_defaults("static_library") {
-  configs = _default_common_binary_configs
-}
-
-set_defaults("shared_library") {
-  configs = _default_common_binary_configs
-}
-
-set_defaults("source_set") {
-  configs = _default_common_binary_configs
-}
+# This BUILDCONFIG file tells GN how to build upstream Pigweed. When starting a
+# new project, you'll need to copy this file to your project and then modify it
+# to fit your needs. Due to the way Pigweed handles file imports, you won't be
+# able to simply import this file in your own BUILDCONFIG.gn.
+#
+# Keep in mind when importing .gni files that `gn format` will try to
+# alphabetically sort imports unless they're separated by comments. For this
+# file, import order matters (modules.gni MUST be imported first).
 
 declare_args() {
+  # Location of the Pigweed modules directory (defaults to the directory of
+  # this file). When copying this buildconfig into a new project, this should
+  # be modified to point to the location of the Pigweed repository.
+  dir_pigweed = get_path_info(get_path_info("BUILDCONFIG.gn", "abspath"), "dir")
+
   # Path to the Pigweed variables config file for the build target.
   #
   # When this is changed, you must run `ninja -t clean` to remove any files from
@@ -44,8 +34,23 @@ declare_args() {
   pw_target_config = "$dir_pigweed/targets/host/host.gni"
 }
 
+# Import variables that provide paths to modules. Pigweed's GN build requires
+# that this file is imported, and it MUST be imported before any other Pigweed
+# .gni files (as they depend on the dir_[module] variables).
+import("$dir_pigweed/modules.gni")
+
+# Import default GN configurations. This file provides default configurations
+# for upstream Pigweed development, and projects are free to provide their own
+# variation of this file. (depends on modules.gni)
+import("$dir_pigweed/gn_defaults.gni")
+
+# Import target configuration. This is what "completes" a Pigweed configuration.
+# This file should set a default toolchain, configure pw_executable, select
+# backends to build against, and provide target-specific build arguments.
 import(pw_target_config)
 
+# Ensure some sort of default toolchain was provided by the target, and then
+# set the default toolchain.
 assert(pw_target_toolchain != "",
        "Build target must provide its own toolchain.")
 set_default_toolchain(pw_target_toolchain)

gn_defaults.gni

@@ -0,0 +1,40 @@
+# Copyright 2020 The Pigweed Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License. You may obtain a copy of
+# the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+# This file sets defaults for the different GN/Ninja target types in a way that
+# is suitable for upstream Pigweed development. Projects using Pigweed are
+# welcome to import a modified version of this in their BUILDCONFIG.gn, or may
+# choose not to import it altogether.
+
+# Default configs to use for all binary build targets.
+_default_common_binary_configs = [
+  "$dir_pw_build:reduced_size",
+  "$dir_pw_build:strict_warnings",
+]
+
+set_defaults("executable") {
+  configs = _default_common_binary_configs
+}
+
+set_defaults("static_library") {
+  configs = _default_common_binary_configs
+}
+
+set_defaults("shared_library") {
+  configs = _default_common_binary_configs
+}
+
+set_defaults("source_set") {
+  configs = _default_common_binary_configs
+}

modules.gni

@@ -16,12 +16,6 @@
 # allows modules to be moved or swapped out without breaking existing builds.
 # All module variables are prefixed with dir_.
 
-declare_args() {
-  # Location of the Pigweed modules directory (defaults to the directory of
-  # this file).
-  dir_pigweed = get_path_info(get_path_info("BUILD.gn", "abspath"), "dir")
-}
-
 dir_pw_bloat = "$dir_pigweed/pw_bloat"
 dir_pw_build = "$dir_pigweed/pw_build"
 dir_pw_cpu_exception = "$dir_pigweed/pw_cpu_exception"