[Notes] [Git][BuildStream/buildstream][jonathan/debug-remote-failed-buil

Jonathan Maw pushed to branch jonathan/debug-remote-failed-builds at BuildStream / buildstream

Commits:

c31ed138

by Tristan Van Berkom at 2018-10-14T15:24:53Z

CONTRIBUTING.rst: Added more guidelines about documenting the user guide

b39d87b4

by Jürg Billeter at 2018-10-15T11:07:05Z

_artifactcache: Fix crash in push_directory() without artifact server

Fixes #708.

4e3ec89e

by Jürg Billeter at 2018-10-15T11:48:16Z

Merge branch 'juerg/remote-config' into 'master'

_artifactcache: Fix crash in push_directory() without artifact server

Closes #708

See merge request BuildStream/buildstream!871

1f12658d

by Jonathan Maw at 2018-10-15T12:52:00Z

element.py: Always clean up the rootdir

We shouldn't need it to persist now that we cache failed build dirs.

This change breaks the test
`tests/integration/shell.py::test_sysroot_workspace_visible`.
I can no longer see a use-case for this test.
AIUI, it tested that the failed build sysroot stored in the builddir has
the workspace's files in, despite the workspace being unmounted.
I believe this behaviour is made redundant by cached buildtrees.

This fixes part of #539

c73de158

by Jonathan Maw at 2018-10-15T12:52:00Z

Element: Use cached buildtree in build shells and failure shells

This includes changes in app.py:
* Interactive failure shell no longer uses the failed build sysroot,
  defaulting to the cached build tree.
* Always allow producing a failure shell.

Changes in element.py are:
* Errors caused by building don't store the failed build sysroot.
* When staging sources, will stage the element's cached build tree if it
  exists.

This fixes part of #539

03f5c33e

by Jonathan Maw at 2018-10-15T12:52:00Z

NEWS: Add item for cached buildtree behaviour

025488c0

by Jonathan Maw at 2018-10-15T12:52:00Z

tests: Add test that cached build trees are staged in build shells

This is related to #539

7b178788

by Jonathan Maw at 2018-10-15T12:52:00Z

sandbox.py: Remove redundant Sandbox.__directory

fd8d3d25

by Jonathan Maw at 2018-10-15T12:52:00Z

element: Make "--sysroot" take a bare directory

i.e. instead of taking a directory that must contain "root" and
"scratch", and treating "root" as the root, use the directory directly.

In element.py:
* __sandbox takes the `bare_sandbox` arg, to pass into the sandbox's constructor

In sandbox.py:
* If bare_sandbox, `_root` is the passed-in directory, and `__scratch`
  is None.
* Trying to use `__scratch` when bare_sandbox is True is a bug.

In _mount.py:
* Don't get the value of `__scratch` if it's not needed.

This is part of #539

88ed3990

by Jonathan Maw at 2018-10-15T12:52:00Z

NEWS: Add item for bst shell --sysroot changes

9827a94f

by Jonathan Maw at 2018-10-15T12:52:01Z

tests: Add tests for 'bst shell --sysroot'

This is related to #539

13 changed files:

CONTRIBUTING.rst
NEWS
buildstream/_artifactcache/cascache.py
buildstream/_frontend/app.py
buildstream/element.py
buildstream/sandbox/_mount.py
buildstream/sandbox/sandbox.py
doc/source/main_using.rst
doc/source/using_examples.rst
doc/source/using_tutorial.rst
+ tests/integration/build-tree.py
+ tests/integration/project/elements/build-shell/buildtree.bst
tests/integration/shell.py

Changes:

CONTRIBUTING.rst

@@ -1147,7 +1147,7 @@ To actually regenerate the code::
  Documenting
  -----------
  BuildStream starts out as a documented project from day one and uses
 -sphinx to document itself.
 +`sphinx <www.sphinx-doc.org>`_ to document itself.
  This section discusses formatting policies for editing files in the
  ``doc/source`` directory, and describes the details of how the docs are
@@ -1194,10 +1194,8 @@ The BuildStream documentation style is as follows:
      the target, e.g.: ``:ref:`Link text <anchor_name>```.
      Note that the "_" prefix is not used when referring to the target.
 -Useful links:
+-
 -For further information, please see the `Sphinx Documentation
 -<http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
 +For further information about using the reStructuredText with sphinx, please see the
 +`Sphinx Documentation <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
  Building Docs
@@ -1266,10 +1264,101 @@ the ``man/`` subdirectory, which will be automatically included
  in the buildstream distribution.
 -Documentation Examples
 -~~~~~~~~~~~~~~~~~~~~~~
 -The examples section of the documentation contains a series of standalone
 -examples, here are the criteria for an example addition.
 +User guide
 +~~~~~~~~~~
 +The :ref:`user guide <using>` is comprised of free form documentation
 +in manually written ``.rst`` files and is split up into a few sections,
 +of main interest are the :ref:`tutorial <tutorial>` and the
 +:ref:`examples <examples>`.
++
 +The distinction of the two categories of user guides is important to
 +understand too.
++
 +* **Tutorial**
++
 +  The tutorial is structured as a series of exercises which start with
 +  the most basic concepts and build upon the previous chapters in order
 +  to arrive at a basic understanding of how to create BuildStream projects.
++
 +  This series of examples should be easy enough to complete in a matter
 +  of a few hours for a new user, and should provide just enough insight to
 +  get the user started in creating their own projects.
++
 +  Going through the tutorial step by step should also result in the user
 +  becoming proficient enough with the reference manual to get by on their own.
++
 +* **Examples**
++
 +  These exist to demonstrate how to accomplish more advanced tasks which
 +  are not always obvious and discoverable.
++
 +  Alternatively, these also demonstrate elegant and recommended ways of
 +  accomplishing some tasks which could be done in various ways.
++
++
 +Guidelines
 +''''''''''
 +Here are some general guidelines for adding new free form documentation
 +to the user guide.
++
 +* **Focus on a single subject**
++
 +  It is important to stay focused on a single subject and avoid getting
 +  into tangential material when creating a new entry, so that the articles
 +  remain concise and the user is not distracted by unrelated subject material.
++
 +  A single tutorial chapter or example should not introduce any additional
 +  subject material than the material being added for the given example.
++
 +* **Reuse existing sample project elements**
++
 +  To help avoid distracting from the topic at hand, it is always preferable to
 +  reuse the same project sample material from other examples and only deviate
 +  slightly to demonstrate the new material, than to create completely new projects.
++
 +  This helps us remain focused on a single topic at a time, and reduces the amount
 +  of unrelated material the reader needs to learn in order to digest the new
 +  example.
++
 +* **Don't be redundant**
++
 +  When something has already been explained in the tutorial or in another example,
 +  it is best to simply refer to the other user guide entry in a new example.
++
 +  Always prefer to link to the tutorial if an explanation exists in the tutorial,
 +  rather than linking to another example, where possible.
++
 +* **Link into the reference manual at every opportunity**
++
 +  The format and plugin API is 100% documented at all times. Whenever discussing
 +  anything about the format or plugin API, always do so while providing a link
 +  into the more terse reference material.
++
 +  We don't want users to have to search for the material themselves, and we also
 +  want the user to become proficient at navigating the reference material over
 +  time.
++
 +* **Use concise terminology**
++
 +  As developers, we tend to come up with code names for features we develop, and
 +  then end up documenting a new feature in an example.
++
 +  Never use a code name or shorthand to refer to a feature in the user guide, instead
 +  always use fully qualified sentences outlining very explicitly what we are doing
 +  in the example, or what the example is for in the case of a title.
++
 +  We need to be considerate that the audience of our user guide is probably a
 +  proficient developer or integrator, but has no idea what we might have decided
 +  to name a given activity.
++
++
 +Structure of an example
 +'''''''''''''''''''''''
 +The :ref:`tutorial <tutorial>` and the :ref:`examples <examples>` sections
 +of the documentation contain a series of sample projects, each chapter in
 +the tutoral, or standalone example uses a sample project.
++
 +Here is the the structure for adding new examples and tutorial chapters.
  * The example has a ``${name}``.
@@ -1280,11 +1369,17 @@ examples, here are the criteria for an example addition.
  * The example has a documentation component.
    * This is added at ``doc/source/examples/${name}.rst``
 -  * A reference to ``examples/${name}`` is added to the toctree in ``doc/source/examples.rst``
 +  * An entry for ``examples/${name}`` is added to the toctree in ``doc/source/using_examples.rst``
    * This documentation discusses the project elements declared in the project and may
      provide some BuildStream command examples.
    * This documentation links out to the reference manual at every opportunity.
 +  .. note::
++
 +     In the case of a tutorial chapter, the ``.rst`` file is added in at
 +     ``doc/source/tutorial/${name}.rst`` and an entry for ``tutorial/${name}``
 +     is added to ``doc/source/using_tutorial.rst``.
++
  * The example has a CI test component.
    * This is an integration test added at ``tests/examples/${name}``.

NEWS

@@ -27,6 +27,14 @@ buildstream 1.3.1
    o Generate Docker images from built artifacts using
      `contrib/bst-docker-import` script.
 +  o Creating a build shell through the interactive mode or `bst shell
 +    --build` will now use the cached build tree. It is now *easier* to debug
 +    local build failures, and *possible* to debug remote build failures.
++
 +  o `bst shell --sysroot` now takes any directory that contains a sysroot,
 +    instead of just a specially-formatted build-root with a `root` and `scratch`
 +    subdirectory.
++
  =================
  buildstream 1.1.5

buildstream/_artifactcache/cascache.py

@@ -365,7 +365,10 @@ class CASCache(ArtifactCache):
          Raises: ArtifactError if no push remotes are configured.
          """
 -        push_remotes = [r for r in self._remotes[project] if r.spec.push]
 +        if self._has_push_remotes:
 +            push_remotes = [r for r in self._remotes[project] if r.spec.push]
 +        else:
 +            push_remotes = []
          if not push_remotes:
              raise ArtifactError("CASCache: push_directory was called, but no remote artifact " +

buildstream/_frontend/app.py

@@ -564,18 +564,15 @@ class App():
                         "  (c)ontinue  - Continue queueing jobs as much as possible\n" +
                         "  (q)uit      - Exit after all ongoing jobs complete\n" +
                         "  (t)erminate - Terminate any ongoing jobs and exit\n" +
 -                       "  (r)etry     - Retry this job\n")
 +                       "  (r)etry     - Retry this job\n" +
 +                       "  (s)hell     - Drop into a shell in the failed build sandbox\n")
              if failure.logfile:
                  summary += "  (l)og       - View the full log file\n"
 -            if failure.sandbox:
 -                summary += "  (s)hell     - Drop into a shell in the failed build sandbox\n"
              summary += "\nPressing ^C will terminate jobs and exit\n"
 -            choices = ['continue', 'quit', 'terminate', 'retry']
 +            choices = ['continue', 'quit', 'terminate', 'retry', 'shell']
              if failure.logfile:
                  choices += ['log']
 -            if failure.sandbox:
 -                choices += ['shell']
              choice = ''
              while choice not in ['continue', 'quit', 'terminate', 'retry']:
@@ -595,10 +592,10 @@ class App():
                  # Handle choices which you can come back from
+                 #
                  if choice == 'shell':
 -                    click.echo("\nDropping into an interactive shell in the failed build sandbox\n", err=True)
 +                    click.echo("\nDropping into an interactive shell in the failed build tree\n", err=True)
                      try:
                          prompt = self.shell_prompt(element)
 -                        self.stream.shell(element, Scope.BUILD, prompt, directory=failure.sandbox, isolate=True)
 +                        self.stream.shell(element, Scope.BUILD, prompt, isolate=True)
                      except BstError as e:
                          click.echo("Error while attempting to create interactive shell: {}".format(e), err=True)
                  elif choice == 'log':

buildstream/element.py

@@ -1317,7 +1317,9 @@ class Element(Plugin):
      @contextmanager
      def _prepare_sandbox(self, scope, directory, deps='run', integrate=True):
          # bst shell and bst checkout require a local sandbox.
 -        with self.__sandbox(directory, config=self.__sandbox_config, allow_remote=False) as sandbox:
 +        bare_directory = True if directory else False
 +        with self.__sandbox(directory, config=self.__sandbox_config, allow_remote=False,
 +                            bare_directory=True if directory else False) as sandbox:
              # Configure always comes first, and we need it.
              self.configure_sandbox(sandbox)
@@ -1384,6 +1386,7 @@ class Element(Plugin):
              # the same filing system as the rest of our cache.
              temp_staging_location = os.path.join(self._get_context().artifactdir, "staging_temp")
              temp_staging_directory = tempfile.mkdtemp(prefix=temp_staging_location)
 +            import_dir = temp_staging_directory
              try:
                  workspace = self._get_workspace()
@@ -1394,12 +1397,16 @@ class Element(Plugin):
                          with self.timed_activity("Staging local files at {}"
                                                   .format(workspace.get_absolute_path())):
                              workspace.stage(temp_staging_directory)
 +                elif self._cached():
 +                    # We have a cached buildtree to use, instead
 +                    artifact_base, _ = self.__extract()
 +                    import_dir = os.path.join(artifact_base, 'buildtree')
                  else:
                      # No workspace, stage directly
                      for source in self.sources():
                          source._stage(temp_staging_directory)
 -                vdirectory.import_files(temp_staging_directory)
 +                vdirectory.import_files(import_dir)
              finally:
                  # Staging may produce directories with less than 'rwx' permissions
@@ -1565,10 +1572,6 @@ class Element(Plugin):
                      collect = self.assemble(sandbox)
                      self.__set_build_result(success=True, description="succeeded")
                  except BstError as e:
 -                    # If an error occurred assembling an element in a sandbox,
 -                    # then tack on the sandbox directory to the error
 -                    e.sandbox = rootdir
+-
                      # If there is a workspace open on this element, it will have
                      # been mounted for sandbox invocations instead of being staged.
+                     #
@@ -1682,8 +1685,8 @@ class Element(Plugin):
                              "unable to collect artifact contents"
                              .format(collect))
 -            # Finally cleanup the build dir
 -            cleanup_rootdir()
 +                    # Finally cleanup the build dir
 +                    cleanup_rootdir()
          return artifact_size
@@ -2151,12 +2154,14 @@ class Element(Plugin):
      #    stderr (fileobject): The stream for stderr for the sandbox
      #    config (SandboxConfig): The SandboxConfig object
      #    allow_remote (bool): Whether the sandbox is allowed to be remote
 +    #    bare_directory (bool): Whether the directory is bare i.e. doesn't have
 +    #                           a separate 'root' subdir
+     #
      # Yields:
      #    (Sandbox): A usable sandbox
+     #
      @contextmanager
 -    def __sandbox(self, directory, stdout=None, stderr=None, config=None, allow_remote=True):
 +    def __sandbox(self, directory, stdout=None, stderr=None, config=None, allow_remote=True, bare_directory=False):
          context = self._get_context()
          project = self._get_project()
          platform = Platform.get_platform()
@@ -2187,6 +2192,7 @@ class Element(Plugin):
                                                stdout=stdout,
                                                stderr=stderr,
                                                config=config,
 +                                              bare_directory=bare_directory,
                                                allow_real_directory=not self.BST_VIRTUAL_DIRECTORY)
              yield sandbox
@@ -2196,7 +2202,7 @@ class Element(Plugin):
              # Recursive contextmanager...
              with self.__sandbox(rootdir, stdout=stdout, stderr=stderr, config=config,
 -                                allow_remote=allow_remote) as sandbox:
 +                                allow_remote=allow_remote, bare_directory=False) as sandbox:
                  yield sandbox
              # Cleanup the build dir

buildstream/sandbox/_mount.py

@@ -31,7 +31,6 @@ from .._fuse import SafeHardlinks
+ #
  class Mount():
      def __init__(self, sandbox, mount_point, safe_hardlinks, fuse_mount_options={}):
 -        scratch_directory = sandbox._get_scratch_directory()
          # Getting _get_underlying_directory() here is acceptable as
          # we're part of the sandbox code. This will fail if our
          # directory is CAS-based.
@@ -51,6 +50,7 @@ class Mount():
          #        a regular mount point within the parent's redirected mount.
+         #
          if self.safe_hardlinks:
 +            scratch_directory = sandbox._get_scratch_directory()
              # Redirected mount
              self.mount_origin = os.path.join(root_directory, mount_point.lstrip(os.sep))
              self.mount_base = os.path.join(scratch_directory, utils.url_directory_name(mount_point))

buildstream/sandbox/sandbox.py

@@ -98,16 +98,23 @@ class Sandbox():
          self.__config = kwargs['config']
          self.__stdout = kwargs['stdout']
          self.__stderr = kwargs['stderr']
 +        self.__bare_directory = kwargs['bare_directory']
          # Setup the directories. Root and output_directory should be
          # available to subclasses, hence being single-underscore. The
          # others are private to this class.
 -        self._root = os.path.join(directory, 'root')
 +        # If the directory is bare, it probably doesn't need scratch
 +        if self.__bare_directory:
 +            self._root = directory
 +            self.__scratch = None
 +            os.makedirs(self._root, exist_ok=True)
 +        else:
 +            self._root = os.path.join(directory, 'root')
 +            self.__scratch = os.path.join(directory, 'scratch')
 +            for directory_ in [self._root, self.__scratch]:
 +                os.makedirs(directory_, exist_ok=True)
++
          self._output_directory = None
 -        self.__directory = directory
 -        self.__scratch = os.path.join(self.__directory, 'scratch')
 -        for directory_ in [self._root, self.__scratch]:
 -            os.makedirs(directory_, exist_ok=True)
          self._vdir = None
          # This is set if anyone requests access to the underlying
@@ -332,6 +339,7 @@ class Sandbox():
      # Returns:
      #    (str): The sandbox scratch directory
      def _get_scratch_directory(self):
 +        assert not self.__bare_directory, "Scratch is not going to work with bare directories"
          return self.__scratch
      # _get_output()

doc/source/main_using.rst

 +.. _using:
++
  Using
  =====
  This section includes user facing documentation including tutorials,

doc/source/using_examples.rst

++
 +.. _examples:
++
  Examples
  ========
  This page contains documentation for real examples of BuildStream projects,

doc/source/using_tutorial.rst

++
 +.. _tutorial:
++
  Tutorial
  ========
  This is a step by step walkthrough meant help the user quickly get

tests/integration/build-tree.py

 +import os
 +import pytest
 +import shutil
++
 +from tests.testutils import cli, cli_integration, create_artifact_share
++
++
 +pytestmark = pytest.mark.integration
++
++
 +DATA_DIR = os.path.join(
 +    os.path.dirname(os.path.realpath(__file__)),
 +    "project"
 +)
++
++
 +@pytest.mark.datafiles(DATA_DIR)
 +def test_buildtree_staged(cli_integration, tmpdir, datafiles):
 +    # i.e. tests that cached build trees are staged by `bst shell --build`
 +    project = os.path.join(datafiles.dirname, datafiles.basename)
 +    element_name = 'build-shell/buildtree.bst'
++
 +    res = cli_integration.run(project=project, args=['build', element_name])
 +    res.assert_success()
++
 +    res = cli_integration.run(project=project, args=[
 +        'shell', '--build', element_name, '--', 'grep', '-q', 'Hi', 'test'
 +    ])
 +    res.assert_success()
++
++
 +# Check that build shells work when pulled from a remote cache
 +# This is to roughly simulate remote execution
 +@pytest.mark.datafiles(DATA_DIR)
 +def test_buildtree_pulled(cli, tmpdir, datafiles):
 +    project = os.path.join(datafiles.dirname, datafiles.basename)
 +    element_name = 'build-shell/buildtree.bst'
++
 +    with create_artifact_share(os.path.join(str(tmpdir), 'artifactshare')) as share:
 +        # Build the element to push it to cache
 +        cli.configure({
 +            'artifacts': {'url': share.repo, 'push': True}
 +        })
 +        result = cli.run(project=project, args=['build', element_name])
 +        result.assert_success()
 +        assert cli.get_element_state(project, element_name) == 'cached'
++
 +        # Discard the cache
 +        cli.configure({
 +            'artifacts': {'url': share.repo, 'push': True},
 +            'artifactdir': os.path.join(cli.directory, 'artifacts2')
 +        })
 +        assert cli.get_element_state(project, element_name) != 'cached'
++
 +        # Pull from cache
 +        result = cli.run(project=project, args=['pull', '--deps', 'all', element_name])
 +        result.assert_success()
++
 +        # Check it's using the cached build tree
 +        res = cli.run(project=project, args=[
 +            'shell', '--build', element_name, '--', 'grep', '-q', 'Hi', 'test'
 +        ])
 +        res.assert_success()

tests/integration/project/elements/build-shell/buildtree.bst

 +kind: manual
 +description: |
 +  Puts a file in the build tree so that build tree caching and staging can be tested.
++
 +depends:
 +  - filename: base.bst
 +    type: build
++
 +config:
 +  build-commands:
 +    - "echo 'Hi' > %{build-root}/test"

tests/integration/shell.py

@@ -302,46 +302,33 @@ def test_workspace_visible(cli, tmpdir, datafiles):
      assert result.output == workspace_hello
 -# Test that we can see the workspace files in a shell
 -@pytest.mark.integration
 +# Test that '--sysroot' works
  @pytest.mark.datafiles(DATA_DIR)
 -def test_sysroot_workspace_visible(cli, tmpdir, datafiles):
 +def test_sysroot(cli, tmpdir, datafiles):
      project = os.path.join(datafiles.dirname, datafiles.basename)
 -    workspace = os.path.join(cli.directory, 'workspace')
 -    element_name = 'workspace/workspace-mount-fail.bst'
+-
 -    # Open a workspace on our build failing element
 -    #
 -    res = cli.run(project=project, args=['workspace', 'open', element_name, workspace])
 -    assert res.exit_code == 0
+-
 -    # Ensure the dependencies of our build failing element are built
 -    result = cli.run(project=project, args=['build', element_name])
 -    result.assert_main_error(ErrorDomain.STREAM, None)
+-
 -    # Discover the sysroot of the failed build directory, after one
 -    # failed build, there should be only one directory there.
 -    #
 -    build_base = os.path.join(cli.directory, 'build')
 -    build_dirs = os.listdir(path=build_base)
 -    assert len(build_dirs) == 1
 -    build_dir = os.path.join(build_base, build_dirs[0])
+-
 -    # Obtain a copy of the hello.c content from the workspace
 -    #
 -    workspace_hello_path = os.path.join(cli.directory, 'workspace', 'hello.c')
 -    assert os.path.exists(workspace_hello_path)
 -    with open(workspace_hello_path, 'r') as f:
 -        workspace_hello = f.read()
+-
 -    # Cat the hello.c file from a bst shell command, and assert
 -    # that we got the same content here
 -    #
 -    result = cli.run(project=project, args=[
 -        'shell', '--build', '--sysroot', build_dir, element_name, '--', 'cat', 'hello.c'
 +    base_element = "base/base-alpine.bst"
 +    # test element only needs to be something lightweight for this test
 +    test_element = "script/script.bst"
 +    checkout_dir = os.path.join(str(tmpdir), 'alpine-sysroot')
 +    test_file = 'hello'
++
 +    # Build and check out a sysroot
 +    res = cli.run(project=project, args=['build', base_element])
 +    res.assert_success()
 +    res = cli.run(project=project, args=['checkout', base_element, checkout_dir])
 +    res.assert_success()
++
 +    # Mutate the sysroot
 +    test_path = os.path.join(checkout_dir, test_file)
 +    with open(test_path, 'w') as f:
 +        f.write('hello\n')
++
 +    # Shell into the sysroot and check the test file exists
 +    res = cli.run(project=project, args=[
 +        'shell', '--build', '--sysroot', checkout_dir, test_element, '--',
 +        'grep', '-q', 'hello', '/' + test_file
      ])
 -    assert result.exit_code == 0
 -    assert result.output == workspace_hello
 +    res.assert_success()
  # Test system integration commands can access devices in /dev

[Notes] [Git][BuildStream/buildstream][jonathan/debug-remote-failed-builds] 11 commits: CONTRIBUTING.rst: Added more guidelines about documenting the user guide

Jonathan Maw pushed to branch jonathan/debug-remote-failed-builds at BuildStream / buildstream

Commits:

13 changed files:

Changes: