Hi all, Today was my first experience using Buildstream, which I did by following the guide on the GNOME wiki <https://wiki.gnome.org/Newcomers/BuildSystemComponent>. I got blocked by an issue <https://gitlab.com/BuildStream/buildstream/issues/216>, but I wanted to provide some notes on my experience using the documentation (see below).
I'm coming at this from the perspective of someone who regularly builds GNOME components, but who isn't a developer. I'm used to the old JHBuild tutorial, which offered a clear set of steps that I found easy to follow. If I manage to progress further, I'll share more feedback. Thanks, Allan -- *Installation* <https://wiki.gnome.org/Newcomers/BuildSystemComponent#Install_BuildStream> The page sends me to an installation guide <https://buildstream.gitlab.io/buildstream/install.html>, which isn't that easy to follow: - 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 buildstream* <https://wiki.gnome.org/Newcomers/BuildSystemComponent#Configuring_BuildStream> The 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 <http://buildstream.gitlab.io/buildstream/config.html#config>, 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. *Building GNOME* <https://wiki.gnome.org/Newcomers/BuildSystemComponent#Building_GNOME> "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 <https://wiki.gnome.org/Projects/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. Partly due to the above, it isn't clear what the "tracking new sources" and "fetching the latest build metadata" sections are for - it doesn't explain what they do, when I should use them, or how they're relevant. It says that the latter is "worth a mention" - this leaves me in some doubt as to whether it's important or not.
_______________________________________________ release-team@gnome.org https://mail.gnome.org/mailman/listinfo/release-team Release-team lurker? Do NOT participate in discussions.
