2. Workspaces and subprojects

When developping a project with junctions and subprojects, you will probably end up needing to work on the subprojects as well.

Opening workspaces works mostly in the same way as it does with subprojects as it does for elements directly in your own project.

Note

This section runs commands on the same example project presented in the previous section, which is distributed with BuildStream in the doc/examples/junctions subdirectory.

2.1. Workspacing a junction

Sometimes you need to work on the elements declared in a subproject directly. As the downstream consumer of a junctioned project, it makes sense that you might need to work on that project as well in order to satisfy the needs of your downstream project.

You can easily work on your subproject by opening a workspace on the junction element directly.

user@host:~/junctions$ bst workspace open --directory workspace_subproject hello-junction.bst

[--:--:--][        ][    main:core activity                 ] START   Loading elements
[00:00:00][        ][    main:core activity                 ] SUCCESS Loading elements
[--:--:--][        ][    main:core activity                 ] START   Resolving elements
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1723732133.903617    6359 config.cc:230] gRPC experiments enabled: call_status_override_on_cancellation, event_engine_dns, event_engine_listener, http2_stats_fix, monitoring_experiment, pick_first_new, trace_record_callops, work_serializer_clears_time_cache
[00:00:00][        ][    main:core activity                 ] SUCCESS Resolving elements
[--:--:--][        ][    main:core activity                 ] START   Initializing remote caches
[00:00:00][        ][    main:core activity                 ] SUCCESS Initializing remote caches
[--:--:--][        ][    main:core activity                 ] START   Query cache
[00:00:00][        ][    main:core activity                 ] SUCCESS Query cache
[--:--:--][        ][    main:core activity                 ] STATUS  Creating workspace for element hello-junction.bst
[--:--:--][6d2e5da0][    main:hello-junction.bst            ] START   Staging sources to /home/user/buildstream/doc/examples/junctions/workspace_subproject
[--:--:--][        ][    main:hello-junction.bst            ] START   Staging local files into CAS
[00:00:00][        ][    main:hello-junction.bst            ] SUCCESS Staging local files into CAS
[00:00:00][6d2e5da0][    main:hello-junction.bst            ] SUCCESS Staging sources to /home/user/buildstream/doc/examples/junctions/workspace_subproject
[--:--:--][        ][    main:core activity                 ] INFO    Created a workspace for element hello-junction.bst

After opening a workspace on the junction element, the open workspace is used to define the subproject, allowing you to make changes to how the subproject is built, add new dependencies and configure the subproject in any way.

2.2. Cross-junction workspaces

You can open workspaces for elements in the project refered to by the junction using the syntax bst open ${junction-name}:{element-name}. In this example,

user@host:~/junctions$ bst workspace open --directory workspace_hello hello-junction.bst:hello.bst

[--:--:--][        ][    main:core activity                 ] START   Loading elements
WARNING: All log messages before absl::InitializeLog() is called are written to STDERR
I0000 00:00:1723732134.312699    6388 config.cc:230] gRPC experiments enabled: call_status_override_on_cancellation, event_engine_dns, event_engine_listener, http2_stats_fix, monitoring_experiment, pick_first_new, trace_record_callops, work_serializer_clears_time_cache
[--:--:--][7b4aac95][   fetch:hello-junction.bst            ] START   junctions/hello-junction/7b4aac95-fetch.20240815-142854.log
[00:00:00][7b4aac95][   fetch:hello-junction.bst            ] SUCCESS junctions/hello-junction/7b4aac95-fetch.20240815-142854.log
[00:00:00][        ][    main:core activity                 ] SUCCESS Loading elements
[--:--:--][        ][    main:core activity                 ] START   Resolving elements
[00:00:00][        ][    main:core activity                 ] SUCCESS Resolving elements
[--:--:--][        ][    main:core activity                 ] START   Initializing remote caches
[00:00:00][        ][    main:core activity                 ] SUCCESS Initializing remote caches
[--:--:--][        ][    main:core activity                 ] START   Query cache
[00:00:00][        ][    main:core activity                 ] SUCCESS Query cache
[--:--:--][        ][    main:core activity                 ] STATUS  Creating workspace for element hello.bst
[--:--:--][ffeab612][    main:hello-junction.bst:hello.bst  ] START   Staging sources to /home/user/buildstream/doc/examples/junctions/workspace_hello
[00:00:00][ffeab612][    main:hello-junction.bst:hello.bst  ] SUCCESS Staging sources to /home/user/buildstream/doc/examples/junctions/workspace_hello
[--:--:--][        ][    main:core activity                 ] INFO    Created a workspace for element hello-junction.bst:hello.bst

This has opened a workspace for the hello.bst element from the autotools project. This workspace can now be used as normal.