aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorFrancois Kritzinger <francois@codesynthesis.com>2021-10-15 10:04:38 +0200
committerFrancois Kritzinger <francois@codesynthesis.com>2021-10-15 10:15:49 +0200
commit2deba1d2577c6508133d360aa7128e70823aeccd (patch)
tree7eaff167dec37601add7c0dfebf5a62f2b0e5a2f
parent3fa46c7e7b24541763676ba97d446780f5233215 (diff)
Doc reviewdoc-review
-rw-r--r--doc/intro.cli38
1 files changed, 32 insertions, 6 deletions
diff --git a/doc/intro.cli b/doc/intro.cli
index 93e4587..01410b2 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -1284,10 +1284,12 @@ to execute it during the build (since it's built for a different target than
what we are running). But even if you are not planning to cross-compile, there
are other good reasons: if you have multiple build configurations for your
project, you may want to share a single build of your tool between them (why
-waste time building the same thing multiple times). And even if you only have
+waste time building the same thing multiple times?). And even if you only have
a single build of your project, you may want to build the tool with different
options (for example, optimized instead of debug).
+@@ TMP I don't think no question mark is wrong, just my preference.
+
You can probably see where this is going: in order to properly support
build-time dependencies, we need to distinguish them from runtime and we need
an ability to build them in a separate build configuration.
@@ -1356,18 +1358,27 @@ import! [metadata] xxd = xxd%exe{xxd}
There are two main differences compared to the way we import the \c{libhello}
library: we request metadata (\c{[metadata]}) and we do immediate importation
-(\c{import!}). Let's briefly discuss what this means (for details, refer to
+(\c{import!}). Let's briefly discuss what this means (for background on target importation, refer to
\l{b#intro-import Target Importation} in the build system manual). Metadata
for an executable contains information that helps the build system do a better
job when an executable is used as part of the build. For example, it includes
the uniform program name to be used for low-verbosity diagnostics as well as
-the version, checksum, and environment that are used to detect changes. While
+the version, checksum, and environment that are used to detect changes. And
immediate importation instructs the build system to skip rule-specific
importation (for example, search for libraries in compiler-specific search
paths) and import the target here and now, failing if that's not possible. It
is usually appropriate for importing executables. Note also that the metadata
can only be requested in immediate importation.
+@@ TMP The way I read it I was expecting to get more details about [metadata]
+ and import! at the above link to \l{b#intro-import Target Importation}.
+
+@@ TMP Because the part about metadata is more than one sentence long, when we
+ get to the immediate importation part (which used to start with While...)
+ it feels like the connection between the two have been lost and as a result
+ I was looking for a second part to the first immediate importation sentence
+ to match the While at the beginning.
+
\N|While requesting the metadata means that you will have a simpler
\c{buildfile} and a more reliable build, it also likely means that you won't
be able to use the system-installed version of the executable since it needs
@@ -1490,8 +1501,8 @@ c++ hello/cxx{hello}@../hello-clang/hello/hello/
ld ../hello-clang/hello/hello/exe{hello}
\
-This time we are not prompted to create another configuration nor is a new
-instance of \c{xxd} gets built \- as we would have expected, the existing host
+This time we are neither prompted to create another configuration nor is a new
+instance of \c{xxd} built \- as we would have expected, the existing host
configuration with the already built \c{xxd} is reused.
From the above output we can see that \c{bdep} creates the host configuration
@@ -1519,11 +1530,14 @@ using hello
Then build the project and see what happens.
-\N|The \c{target} type signifies a configuration for the target or end-result
+\N|The \c{target} type signifies a configuration for the target machine or end-result
of our build. If no type is specified during the configuration creation with
the \c{--type} option (or \c{--config-type} if using \c{bdep-new}), then
\c{target} is assumed.
+@@ TMP Only made it 'target machine' because it's 'host machine' in the next
+ paragraph. It did make sense as it was.
+
The \c{host} type signifies a configuration corresponding to the host machine,
that is, the machine on which the build is performed. It is expected that an
executable built in the host configuration can be executed. Oftentimes, target
@@ -1572,6 +1586,18 @@ Most of the commands are hopefully self-explanatory except for the \c{{
dependency in the \c{base} configuration (we don't have to do the same for
\c{clang} since the dependency is already built).
+@@ TMP (This is new to me so I guess this is what a new user might also
+ wonder:) If @base is as complete a config as @gcc and already linked to it
+ then why can't it just be something like
+
+ $ bdep init @gcc
+ $ bdep init { @base }+ ?libhello
+ $ bdep init @clang
+
+ Just seems like there's some redundancy given that @base has already been
+ configured to use g++ and linked to @gcc. `bdep init @gcc { @base }+
+ ?libhello` feels like a second linking or something. Or is it actually just
+ a combo of the first two commands (directly above)?
\h#guide-versioning-releasing|Versioning and Release Management|