Skip to content

docs/overlaps: Add 'Changing the location' section #2060

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+23 −0
Open

docs/overlaps: Add 'Changing the location' section #2060

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions doc/source/handling-files/overlaps.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,29 @@ command contain an ``rm`` statement, as such:
This would cause later builds of ``runtime-only.bst`` to no longer
conflict on the given file.

Changing the location
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section doesn't fit with the rest of the document. The document discusses an example project, while this section discusses a theoretical example that isn't well defined.

I'm not sure what's the best way to deal with this. Extend the example project so that this can be applied? That could be too complicated for this tutorial. Move it to somewhere else in the documentation? I don't know where that could be.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree that it doesn't /really/ fit with the rest of the document. I
looked through the docs to find an alternative place, but none felt
like a good place.

I guess we could just keep the section in BuildElement and refer to
that from other documentation?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@juergbi @gtristan What are your thoughts on a good way to place this section in the docs?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we could just keep the section in BuildElement and refer to
that from other documentation?

Yes, I think it would be reasonable to add the information from this section to the BuildElement documentation as that's where location is documented. That said, the BuildElement documentation is a bit hidden as it's part of the Plugin API reference even though location is more relevant to project developers than plugin developers. I.e., maybe we could find a better place for the whole location documentation. However, moving that around is not directly related to expanding the documentation to cover the handling of runtime dependencies, so I suggest to first land the expanded documentation in BuildElement and then separately consider moving that section to a more relevant/discoverable part of the documentation.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it is also, separately documented in ScriptElement right ?

There are a couple (slowly growing number) of features which cannot be directly implemented on the Element class but are common amongst abstract subclasses, it can perhaps make sense perhaps to add a page to consolidate documentation for these common features on a single page...

---------------------

Some element kinds allow you to stage their dependencies in certain locations.
This would allow for both versions to exist, separated in different
directories. An important thing to note here is that this does also change the
location of the runtime dependencies of an element. This means that it is
important to check that the element in question can cope with this movement of
its dependencies. Expanding off of this, if two dependencies have the same
runtime dependency and then one is moved, there will now be two copies of that
runtime dependency, one in the original location and one in the moved location.

An example of changing the location of a dependency:

.. code:: yaml

filename: components/example.bst
config:
location: "/test"

The BuildStream documentation for changing the staging location can be found
`here
<https://docs.buildstream.build/master/buildstream.buildelement.html#location-for-staging-dependencies>`__

Summary
-------
Expand Down