diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/intro.cli | 38 |
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| |