Write "getting started" guide #103

Closed Cynical-Optimist closed 4 years ago

See original issue on GitLab In GitLab by [Gitlab user @jonathanmaw] on Oct 4, 2017, 12:17

This should go in https://buildstream.gitlab.io/buildstream/, probably as part of the installation guide

This should cover:

what it's for in a couple of sentencess.
how to install it (via a link if it's complex)
how to do 'hello-world' within 10 minutes, with words people with no bst experience can understand
where to dig deeper

In GitLab by [Gitlab user @samthursfield] on Feb 28, 2018, 14:36

mentioned in merge request buildstream-examples!1

In GitLab by [Gitlab user @samthursfield] on Feb 28, 2018, 14:45

More generally, we need a "Quick start" guide that concisely explains the basic principles of BuildStream, how to run a build, and how to author a simple project.

I had a go at drafting such a thing here: https://wiki.gnome.org/SamThursfield/BuildStreamQuickStart

I structured it in 4 sections:

"What is BuildStream?" -- this section is mostly done
"Building a project" -- showing how to use bst to build and run an existing project. I plan to use the Freedesktop SDK as an example here for want of something better, but a dedicated example from the buildstream-examples repo would probably work better if we had such a thing. This section is maybe half complete.
"Authoring a project" -- showing how to write a project from scratch. I propose using a simple Flatpak app example. This section isn't started.
"Further reading" -- link to reference manual, etc.

My example is not finished; I think the first section is pretty complete and could be used as-is in a quick start guide.

In GitLab by [Gitlab user @devcurmudgeon] on Mar 8, 2018, 17:00

How do we get Sam's doc into the official place? I'd like to submit patches to it...

In GitLab by [Gitlab user @tristanvb] on Mar 9, 2018, 07:40

[Gitlab user @devcurmudgeon]: The docs are in the doc/source/ subdirectory of the buildstream git repo.

They are in reStructuredText markdown, there is a quickstart here but following the material already in place should be fairly straightforward.

The current structure inside doc/source is:

Main page at index.rst
- Docs about using the cli at main_using.rst
- Docs about the format, including list of plugins at main_authoring.rst
- Docs about core API, for writing plugins at main_core.rst

For a quickstart guide, I dont think it belongs in any of these, but probably a link to a new main_quickstart.rst which appears in index.rst before any of the more core reference would be appropriate, this can/should link into the more terse reference material where appropriate.

A note about main_using.rst, this is currently shallow; but there is a plan to add more here about invoking BuildStream, adding more discussion about each command, starting with this: unapplied patch (what this does is link to automatically generated docs for the CLI in sections, allowing extra custom text for each command).

In GitLab by [Gitlab user @tristanvb] on Mar 9, 2018, 08:13

Some additional notes.

To work on documentation, it is important to be able to build the docs and then browse them locally with a file:// url.

I dont know if this is at all possible when using the bst-here wrapper script.

To build documentation, it is mentioned in the HACKING.rst file, but you basically need:

BuildStream to be installed (this should be true inside the bst-here docker container)
Install some additional things:

pip install --user sphinx
pip install --user sphinx-click

Run make -C doc
Figure out where bst-here is running stuff, so that you can access the directory from the host and look at the result in your browser using a file:// url.

In GitLab by [Gitlab user @jjardon] on Mar 15, 2018, 21:41

changed title from {-Provide documentation to create a project from scratch-} to {+Write "getting started" guide+}

In GitLab by [Gitlab user @jjardon] on Mar 15, 2018, 21:41

changed the description

In GitLab by [Gitlab user @jjardon] on Mar 15, 2018, 22:14

mentioned in merge request !323

In GitLab by [Gitlab user @jjardon] on Mar 16, 2018, 11:31

actually, https://gitlab.com/BuildStream/buildstream/issues/103#note_62386189 and https://gitlab.com/BuildStrem/buildstream/issues/103#note_62392709 should be part of the docs somewhere to explain how to contrinute to the docs: opened #303

In GitLab by [Gitlab user @jjardon] on Apr 16, 2018, 17:58

mentioned in merge request !403

In GitLab by [Gitlab user @albfan] on May 11, 2018, 08:31

I'm working on examples section with real examples that will run under CI.

Will ask for MR when MR is ready!

In GitLab by [Gitlab user @albfan] on May 12, 2018, 12:38

mentioned in merge request !463

In GitLab by [Gitlab user @jennis] on May 22, 2018, 17:56

assigned to [Gitlab user @jennis]

In GitLab by [Gitlab user @LaurenceUrhegyi] on May 22, 2018, 18:14

unassigned [Gitlab user @jonathanmaw]

In GitLab by [Gitlab user @jennis] on Jun 13, 2018, 16:59

assigned to [Gitlab user @phildawson]

In GitLab by [Gitlab user @phildawson] on Jun 13, 2018, 17:08

mentioned in merge request !499

In GitLab by [Gitlab user @jennis] on Jun 13, 2018, 17:13

UPDATE: [Gitlab user @phildawson] has taken the current WIP for this issue and has created an MR which introduces another example - importing a minimal alpine image and building amhello with an Autotools build element.

This is both a simple, and minimal, example that we have agreed could serve as our Getting started example.

Note: This MR conforms to the new style of BuildStream examples.

Another note: We also intend to migrate the x86_64 example (here) into the main repo. And we are yet to decide what will be the fate of the netsurf example ([here] (https://gitlab.com/BuildStream/buildstream-examples/tree/master/netsurf-flatpak)). Currently, both of these are not in a "buildable" state.

MR here: https://gitlab.com/BuildStream/buildstream/merge_requests/499

Thank you [Gitlab user @phildawson]

In GitLab by [Gitlab user @jennis] on Jun 13, 2018, 18:14

I also think that the Getting started section should include a description/breakdown of a build element as these are what make up the core of a BuildStream project. However, I don't think it's necessary to include such work in !499, we can do this in a separate MR.

I have some material for this here.

But I would like to know what people's thoughts are before throwing up an MR. [Gitlab user @tristanvb]?

My own current concerns are:

In this example we are describing the gedit.bst element which is part of the gnome-build-meta project. Perhaps we should describe one of our own elements from our "in-house" examples...?
It's another autotools element... When !499 lands, we will have two examples both using autotools elements, perhaps we should have a bit more variety?

I also have some work which describes the motivation and concepts of buildstream (here).

If anyone could spare some time to read this, I'd appreciate your thoughts on whether this is something we should include in the Getting started section. Please don't focus on the specifics too much, just let me know if you think it's generally something that we should include and then we can focus on the specifics of the content.

In GitLab by [Gitlab user @phildawson] on Jun 14, 2018, 11:50

mentioned in commit 6946e86a352f6c99cbfc9bd3e60e9ec3a2bd475a

In GitLab by [Gitlab user @phildawson] on Jun 14, 2018, 11:50

mentioned in commit f8f58d16f61434c03823f755c1d07a36ba36c99e

In GitLab by [Gitlab user @phildawson] on Jun 14, 2018, 11:50

mentioned in commit 5d57664bb371c139a694b5da3e85240130d61ad2

In GitLab by [Gitlab user @phildawson] on Jun 14, 2018, 11:58

mentioned in commit 1195df75e58d19cb77081a0ff57ca0668160b7d2

In GitLab by [Gitlab user @phildawson] on Jun 14, 2018, 11:58

mentioned in commit 772e5a3ed85a43f6ccc8c54f3fab373fd4a89020

In GitLab by [Gitlab user @tristanvb] on Jun 16, 2018, 20:46

mentioned in commit 2d82b7471f349de510fffefb056eba9c0a0550d4

In GitLab by [Gitlab user @tristanvb] on Jun 16, 2018, 20:50

mentioned in commit 95df2d8f6495e3ba80a81094c16b6071baa3d587

In GitLab by [Gitlab user @tristanvb] on Jun 16, 2018, 21:14

mentioned in commit 1b88e2c6f0e3b060d7319e69d9ddf45bed98596f

In GitLab by [Gitlab user @tristanvb] on Jun 16, 2018, 21:51

closed via merge request !501

In GitLab by [Gitlab user @tristanvb] on Jun 18, 2018, 20:18

mentioned in commit b4105e8dea0f4aaaefbbd5a5dce344a939e736dc

In GitLab by [Gitlab user @tristanvb] on Jun 18, 2018, 20:20

mentioned in merge request !507

buildstream-migration / bst-staging

Write "getting started" guide #103