Add docs for pw_env_setup
Change-Id: Ie97a18499040bba4e0061dfa192e81f617c68c9e
diff --git a/docs/BUILD.gn b/docs/BUILD.gn
index f9d371f..aff6fa1 100644
--- a/docs/BUILD.gn
+++ b/docs/BUILD.gn
@@ -47,6 +47,7 @@
"$dir_pw_cpu_exception_armv7m:docs",
"$dir_pw_docgen:docs",
"$dir_pw_doctor:docs",
+ "$dir_pw_env_setup:docs",
"$dir_pw_log:docs",
"$dir_pw_minimal_cpp_stdlib:docs",
"$dir_pw_module:docs",
diff --git a/modules.gni b/modules.gni
index ddc253f..0305438 100644
--- a/modules.gni
+++ b/modules.gni
@@ -28,6 +28,7 @@
dir_pw_cpu_exception_armv7m = "$dir_pigweed/pw_cpu_exception_armv7m"
dir_pw_docgen = "$dir_pigweed/pw_docgen"
dir_pw_doctor = "$dir_pigweed/pw_doctor"
+dir_pw_env_setup = "$dir_pigweed/pw_env_setup"
dir_pw_kvs = "$dir_pigweed/pw_kvs"
dir_pw_log = "$dir_pigweed/pw_log"
dir_pw_log_basic = "$dir_pigweed/pw_log_basic"
diff --git a/pw_env_setup/BUILD.gn b/pw_env_setup/BUILD.gn
new file mode 100644
index 0000000..31d536d
--- /dev/null
+++ b/pw_env_setup/BUILD.gn
@@ -0,0 +1,19 @@
+# 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.
+
+import("$dir_pw_docgen/docs.gni")
+
+pw_doc_group("docs") {
+ sources = [ "docs.rst" ]
+}
diff --git a/pw_env_setup/docs.rst b/pw_env_setup/docs.rst
new file mode 100644
index 0000000..f02930c
--- /dev/null
+++ b/pw_env_setup/docs.rst
@@ -0,0 +1,39 @@
+.. _chapter-pw-env_setup:
+
+------------
+pw_env_setup
+------------
+A classic problem in the embedded space is reducing the time from git clone
+to having a binary executing on a device. The issue is that an entire suite
+of tools is needed for non-trivial production embedded projects. For example:
+
+ - A C++ compiler for your target device, and also for your host
+ - A build system or three; for example, GN, Ninja, CMake, Bazel
+ - A code formatting program like clang-format
+ - A debugger like OpenOCD to flash and debug your embedded device
+ - A known Python version with known modules installed for scripting
+ - A Go compiler for the Go-based command line tools
+
+...and so on
+
+In the server space, container solutions like Docker or Podman solve this;
+however, in our experience container solutions are a mixed bag for embedded
+systems development where one frequently needs access to native system
+resources like USB devices, or must operate on Windows.
+
+pw_env_setup is our compromise solution for this problem that works on Mac,
+Windows, and Linux. It leverages the Chrome packaging system `CIPD`_ to
+bootstrap a Python installation, which in turn inflates a virtual
+environment. The tooling is installed into your workspace, and makes no
+changes to your system. This tooling is designed to be reused by any
+project.
+
+.. _CIPD: https://github.com/luci/luci-go/tree/master/cipd
+
+.. warning::
+ At this time pw_env_setup works for us, but isn’t well tested. We don’t
+ suggest relying on it just yet. However, we are interested in experience
+ reports; if you give it a try, please `send us a note`_ about your
+ experience.
+
+.. _send us a note: pigweed@googlegroups.com