[GitHub] [buildstream] gtristan commented on pull request #1741: Update install instructions for final BuildStream 2.0 release

[GitBox <gi...@apache.org>]

gtristan commented on PR #1741:
URL: https://github.com/apache/buildstream/pull/1741#issuecomment-1227820050

   Overall, I like the install from source instructions here, however it looks like this is unfortunately again growing into a lot of overlap with the user facing instructions at: https://buildstream.build/install.html
   
   ---
   
   I wonder if the statement about *"Installing from distro packages if it is available for your distro"* and the whole convenience packaging method of *"Installation from pip"* is better suited to https://buildstream.build/install.html ... where it appears the pip install method is already mentioned.
   
   Lets keep the user facing install paths published at https://buildstream.build/install.html and have the version specific developer/packager facing instructions at https://docs.buildstream.build/master/main_install.html. This makes the two pages serve obviously different purposes, and makes the reading of either of these less crowded and intense.
   
   ---
   
   It could be good to have a forward in `main_install.rst` saying something like:
   
   > This page explains how to build and install this version of BuildStream from sources. If you are trying to install BuildStream on your computer it is recommended to try following the [general purpose installation instructions here](https://buildstream.build/install.html).
   
   ---
   
   This also goes for the section on *Using docker images*, if there are user facing images ready to be used by users, we should trust https://gitlab.com/BuildStream/buildstream-docker-images/-/blob/master/USING.md to document how to use the latest BuildStream 1 and BuildStream 2 images respectively, and link to that page from the user facing documentation at https://buildstream.build/install.html (without going into a whole detailed shpiel about it)... and of course we should touch up https://gitlab.com/BuildStream/buildstream-docker-images/-/blob/master/USING.md a bit to make sure it at least says `docker run -it -v `pwd`:/build <bst1imagename:latest>` and `docker run -it -v `pwd`:/build <bst2imagename:latest>`.
   
   ---
   
   After trimming out all that fat above, this would leave us with a more manageable structure of only:
   
   * Dependencies for building/running this version of buildstream
     * This would look so much more concise as a condensed table with two columns: *"Distro name"*, and *"Distro specific command"* instead of scrolling down lots of text talking about multiple distros
     * We don't need to separate the dependencies with extra information about "If you need a C++ compiler" I think, this is all about building from source anyway, just specify one command for each distro would be perfect.
   * Installing buildbox
     * Instructions about binaries
     * Link(s) to how to build buildbox from sources in upstream buildbox
   * Cloning the right git tag/branch
   * Installing buildstream from git checkout
     * Here I would remove the whole extra shpiel about *"Upgrading from git"*, if we have instructions to install from git, then the user will figure out that they can always go back and use an updated git version to install
     * Here it could be worth noting that `setup.py` installation is **supported** for both building, installing and testing, because this is the typical distro install path
       * But use `pip install .` as the normal install method
     * Here it is also worth noting that you can make the installation in a python virtual environment
     * Here it is also worth noting that depending on the system prefix or virtual environment where you installed, you may need to set `$PATH` accordingly or activate your virtual environment
       * This part allowing us to remove the conspicuous **Post-install setup** section which is all only about telling you to remember to setup `$PATH`
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@buildstream.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org