- I didn't realise that "User installation with pip" was something I had to do. As a newcomer, it's an odd title - it isn't clear why it is "user installation" or why pip is involved. I would have expected a title like "Install BuildStream" or "Installing BuildStream".
- It doesn't say where to clone the repo.
- It states "If you are installing as a developer" - it isn't clear what this means and I'm not sure whether I'm a developer or not. Am I supposed to be any old developer, or of something specific? If I'm not one of these, what should I do?
Configuring buildstreamThe language in this section is quite permissive - it says what the defaults are, and says what you can do, but this leaves an element of doubt - I would prefer a tutorial that just says exactly what to do.
It tells me to follow a
page on how to configure Buildstream, which gets quite technical. I'm basically not interested in this and it felt like a lot of overhead. I prefer the simple JHBuild tutorial in this regard.
"For developer purposes, we recommend using non strict build planning mode, which only requires a rebuild of any module which has changed since the last build." Like before - am I a developer? Why wouldn't I want this? If it's the best option, why isn't it the default? I'm confused as to the relevance of this statement.
It talks about adding options to ~/.config/buildstream.conf, but this doesn't exist.
"Download the GNOME Build Metadata using git" - it doesn't say which directory I should do this in.
"To build your favorite module" - favorite seems like an odd word to use here, as if I'm building a particular module for kicks.
It wasn't clear to me that I had to run the build command from the gnome-build-meta directory, since the command to switch directories was part of the previous step. This was actually a major stumbling block for me.
The following three sentences mean very little to me, and at times they sound like technobabble:
- "Below is an explanation of how to use the tracking feature
separately. If you have already tracked your sources and just want to
build, simply issue the same above command without the tracking
options:"
- "BuildStream is deterministic at its heart and as such,
it is never enough to say "Build the master branch" alone. This is
because a symbolic branch does not represent a bit-for-bit identical
input for your builds. "
- "In order to get your project into a buildable state, and allow you to easily build the latest commit of a given branch, BuildStream provides the tracking feature to update your project automatically."
These sentences jump into technical details without explaining the basic concepts, particularly what "tracking" means. It's hard to identify a logical progression from one to the other.
