aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2021-10-22 07:54:17 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2021-10-22 07:54:17 +0200
commite3da31f13f9dc2b3ff21350902d0534ac8ebd685 (patch)
treed852d7bed1d46ca941139ecdd3b477ecd588ebc0 /doc
parentbc71de33d429a18cbfe9cc3f0cabb8a9dcc5414b (diff)
Feedback-based improvements to introduction
Diffstat (limited to 'doc')
-rw-r--r--doc/intro.cli36
1 files changed, 24 insertions, 12 deletions
diff --git a/doc/intro.cli b/doc/intro.cli
index d1686a1..79ec41f 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -25,17 +25,11 @@
// - Maximum <pre> line is 70 characters.
//
-"
-\h0#preface|Preface|
-
-This document is an overall introduction to the \c{build2} toolchain that
-shows how the main components, namely the build system, the package dependency
-manager, and the project dependency manager are used together to handle the
-entire C/C++ project development lifecycle: creation, development, testing,
-and delivery. For additional information, including documentation for
-individual toolchain components, man pages, etc., refer to the \c{build2}
-project \l{https://build2.org/doc.xhtml Documentation} page.
-
+// Some people say the find the TLDR "abhorrent" (because it doesn't look
+// like something they can understand without reading the rest of the doc
+// first).
+//
+/*
\h1#tldr|TL;DR|
@@ -100,6 +94,20 @@ synchronizing:
reconfigure hello/0.1.0
\
+*/
+
+"
+\h0#preface|Preface|
+
+This document is an overall introduction to the \c{build2} toolchain that
+shows how the main components, namely the build system, the package dependency
+manager, and the project dependency manager are used together to handle the
+entire C/C++ project development lifecycle: creation, development, testing,
+and delivery. For additional information, including documentation for
+individual toolchain components, man pages, etc., refer to the \c{build2}
+project \l{https://build2.org/doc.xhtml Documentation} page.
+
+
\h1#guide|Getting Started Guide|
The aim of this guide is to get you started developing C/C++ projects with the
@@ -1283,6 +1291,10 @@ be of this kind. However, sometimes we may only wish to use a dependency
during the build, typically a tool, such as a source code generator. This kind
of dependency is called a \i{build-time dependency}.
+\N|Build-time dependencies are an advanced topic and if you don't have an
+immediate need for this functionality, you may skip this section without any
+loss of continuity.|
+
Why do we need to distinguish between the two kinds of dependencies? The
primary reason is cross-compilation: if we build a tool in the same
(cross-compiling) build configuration as our project, then we will not be able
@@ -1346,7 +1358,7 @@ depends: * xxd >= 8.2.0
\
The \c{*} mark in front of the \c{xxd} name indicates that it's a build-time
-dependency (think of \c{*} as the executable mark printed by \c{ls}).
+dependency.
Next we import \c{xxd} in our \c{buildfile}: