Damcilva/2.0/docs/developer guide v2 #5218

dmcilvaney · 2023-04-04T01:22:35Z

Merge Checklist

All boxes should be checked before merging the PR (just tick any boxes which don't apply to this PR)

Summary

Refresh our documentation to better match the current best practices for our toolkit.

Change Log

Update build documentation

Does this affect the toolchain?

NO

rlmenge

A few comments :)

toolkit/docs/building/dedicated_guides/build_images.md

toolkit/docs/building/dedicated_guides/build_packages.md

toolkit/docs/coding_guide/imageconfig.md

Co-authored-by: rlmenge <rlmenge@gmail.com>

…ilvaney/CBL-Mariner into damcilva/2.0/docs/developer_guide_v2

dmcilvaney · 2023-04-07T18:49:48Z

These docs contain references to flags in #5199, will need to merge that first.

aadhar-agarwal · 2023-04-07T19:00:42Z

The docs seem easier to read and understand on first glance! Still going through them :)

PawelWMS · 2023-04-07T23:09:21Z

toolkit/quickrebuild_autoconfig.mk

+
+######## QUICKREBUILD AUTO CONFIGURE ########
+
+# The QUICKREBUILD* flags are special flags that will try to build the toolchain and packages as quickly as possible. They will


Change leak from #5199?

Yes, makes my life easier to validating the commands. Will clean up before the final merge.

christopherco

Reviewed the first half with @dmcilvaney . Will review 2nd half next week.

CONTRIBUTING.md

toolkit/README.md

toolkit/docs/building/building.md

htaubenfeld

I would recommend running these markdowns through ChatGPT and requesting suggestions on tutorial and GitHub docs language and corrections. Let me know if you want to work together on this!

toolkit/Makefile

toolkit/README.md

toolkit/docs/building/building.md

htaubenfeld · 2023-04-10T17:24:14Z

toolkit/docs/building/building.md

+
+|Task                              | Where to go                                                                   |
+|:---------------------------------|-------------------------------------------------------------------------------|
+|Just add or build my own packages | **[CBL-MarinerTutorials](https://github.com/microsoft/CBL-MarinerTutorials)** |


Is there a reason why CBL-MarinerTutorials is bolded?

I want to direct people to the tutorial repo as much as possible. This is the wrong document for 90% of people to be reading and I want to give them as many offramps as possible.

toolkit/docs/building/dedicated_guides/build_images.md

toolkit/docs/building/dedicated_guides/build_packages.md

Co-authored-by: Christopher Co <35273088+christopherco@users.noreply.github.com> Co-authored-by: htaubenfeld <htaubenfeld@microsoft.com>

Co-authored-by: htaubenfeld <htaubenfeld@microsoft.com>

toolkit/docs/building/building.md

Co-authored-by: Christopher Co <35273088+christopherco@users.noreply.github.com>

This reverts commit e82e0be.

This reverts commit b64a58b.

This reverts commit 496c276.

This reverts commit 96c09a1.

This reverts commit 62a0251.

…eveloper_guide_v2

dmcilvaney · 2023-04-17T19:13:47Z

Updated to use actual commits from the quickbuild PR.

tobiasb-ms · 2023-05-12T00:44:08Z

toolkit/docs/building/dedicated_guides/build_packages.md

+# OPTIONAL:
+#   If you want a fast (but possibly less accurate) build, only pack the specific packages we want to build and
+#   use upstream stable packages to fulfill all dependencies.
+pkg_filter="SRPM_PACK_LIST='$packages'"


Do you mean packages here or package_list from line 85?

Thanks! package_list is right, will fix.

tobiasb-ms · 2023-05-12T00:44:22Z

toolkit/docs/building/dedicated_guides/build_packages.md

+#   $toolchain              Where to get our toolchain (see above)
+#   PACKAGE_REBUILD_LIST    List of packages to ALWAYS rebuild, even if they look unchanged (PACKAGE_BUILD_LIST will build them only if they are missing)
+#   SRPM_FILE_SIGNATURE_HANDLING Auto update the signature files
+sudo make build-packages -j$(nproc) QUICK_REBUILD_PACKAGES=y CONFIG_FILE="" REBUILD_TOOLS=y $pkg_filter $toolchain PACKAGE_REBUILD_LIST="$packages" $signature_handle


again -- packages or package_list?

tobiasb-ms · 2023-05-12T02:49:40Z

toolkit/docs/building/dedicated_guides/build_packages.md

+
+# Modify your package
+touch ../SPECS/nano/nano.spec
+touch ../SPECS/nano/opessh.spec


would this be ../SPECS/openssh/openssh.spec

Clearly, I'm just adding a new ssh protocol specialized for use in the Midwest (fixed).

toolkit/docs/building/building.md

trungams

some quick comments, will go through the big building.md doc later

trungams · 2023-06-08T23:13:34Z

CONTRIBUTING.md

-When starting to develop for CBL-Mariner, use the [CBL-MarinerTutorials](https://github.com/microsoft/CBL-MarinerTutorials) repo. This repository guides developers on using CBL-Mariner's tools to customize or add new packages or images. Once you have confirmed your change builds and functions as expected, consider whether it should be added to the core repo, [CBL-Mariner](https://github.com/microsoft/CBL-Mariner). Please see our [quickstart](toolkit/docs/quick_start/quickstart.md) for a tutorial and [building instructions](toolkit/docs/building/building.md) for an in-depth overview of building within CBL-Mariner. Please adhere to the [Pull Request guidelines](pull-request-guidelines) when contributing.
+Start with [CBL-MarinerTutorials](https://github.com/microsoft/CBL-MarinerTutorials) repo. This repository guides developers on using CBL-Mariner's tools to customize or add new packages or images.
+
+Once you have confirmed your change builds and functions as expected, consider whether it should be added to the core repo, [CBL-Mariner](https://github.com/microsoft/CBL-Mariner). Please see our [building instructions](toolkit/README.md) for tutorials and build guides. Please adhere to the [Pull Request guidelines](pull-request-guidelines) when contributing.


Suggested change

Once you have confirmed your change builds and functions as expected, consider whether it should be added to the core repo, [CBL-Mariner](https://github.com/microsoft/CBL-Mariner). Please see our [building instructions](toolkit/README.md) for tutorials and build guides. Please adhere to the [Pull Request guidelines](pull-request-guidelines) when contributing.

Once you have confirmed your change builds and functions as expected, consider whether it should be added to the core repo, [CBL-Mariner](https://github.com/microsoft/CBL-Mariner). Please see our [building instructions](toolkit/README.md) for tutorials and build guides. Please adhere to the [Pull Request guidelines](#pull-request-guidelines) when contributing.

probably need the # for anchor links to work

trungams · 2023-06-08T23:27:52Z

README.md

+
+### [CBL-MarinerTutorials](https://github.com/microsoft/CBL-MarinerTutorials)
+
+The [CBL-MarinerTutorials](https://github.com/microsoft/CBL-MarinerTutorials) repo includes several guides for starting with CBL-Mariner images. The full documentation above also links to it where relaxant.


relaxant -> relevant?

trungams · 2023-06-08T23:29:39Z

SUPPORT.md

@@ -14,4 +14,4 @@ Support for CBL-Mariner is limited to the resources listed above.
 [gh-bug]: https://github.com/microsoft/CBL-Mariner/issues/new?labels=bug
 [gh-feature]: https://github.com/microsoft/CBL-Mariner/issues/new?labels=enhancement
 [tutorial]: https://github.com/Microsoft/CBL-MarinerTutorials
-[contributor]: https://github.com/microsoft/CBL-Mariner/blob/main/CONTRIBUTING.md
+[contributor]: https://github.com/microsoft/CBL-Mariner/blob/-/CONTRIBUTING.md


this whole list fails to render in the actual md page, probably bad formatting?

trungams · 2023-06-08T23:43:53Z

toolkit/docs/quick_start/quickstart.md

@@ -80,17 +95,16 @@ choose DVD Drive and press Add.
 1. Select _Image File:_ and browse to the meta-user-data.iso file.
 1. Select _Apply_ to apply all changes.

-**Boot and Sign-In to your VHD**
+### Boot and Sign-In to your VHD


Suggested change

### Boot and Sign-In to your VHD

### Boot and Sign-In to your VHD(X)

trungams · 2023-06-08T23:49:29Z

toolkit/docs/building/dedicated_guides/build_tools.md

+sudo make go-tools REBUILD_TOOLS=y
+
+# Build a specific tool
+sudo make go-depsearch REBUILD_TOOLS=y


this could be a bit confusing if someone doesn't know depsearch refers to one of the tools' name

trungams · 2023-06-09T00:17:06Z

toolkit/docs/building/dedicated_guides/build_packages.md

+# OPTIONAL:
+#   Build the latest toolchain **if you are NOT working on a stable branch**
+git checkout main
+sudo make toolchain QUICK_REBUILD_TOOLCHAIN=y


Should we have some kind of prerequisites before someone goes through a doc..? I would find these different magic build flags overwhelming with little to no background in the build systems.

The building.md doc is a very comprehensive reference but I'm not sure if that's a good place to start

trungams · 2023-06-09T00:20:34Z

toolkit/docs/building/dedicated_guides/build_packages.md

+sudo make clean QUICK_REBUILD=y
+```
+
+### Build a toolchain if using an unstable branch


Seems like there's many overlaps with the build images doc. Maybe we can separate these first few steps in another doc?

dmcilvaney added 5 commits April 3, 2023 11:39

Add QUICKBUILD flags for fast auto build

62a0251

Rename to QUICKREBUILD

96c09a1

Update toolchain verify output to be more accurate

496c276

Move REBUILD_TOOLS and USE_CCACHE

b64a58b

Fixup

e82e0be

microsoft-github-policy-service bot added the main PR Destined for main label Apr 4, 2023

dmcilvaney force-pushed the damcilva/2.0/docs/developer_guide_v2 branch 2 times, most recently from bd9a336 to dc590b8 Compare April 4, 2023 20:32

1st draft

4c80f24

dmcilvaney force-pushed the damcilva/2.0/docs/developer_guide_v2 branch from dc590b8 to 4c80f24 Compare April 5, 2023 00:35

dmcilvaney added 3 commits April 5, 2023 14:35

Signatures and repo files

26acab2

Redirect quickstart to tutorials faster

b1d3c84

Spelling and more go tools

386c7a2

rlmenge reviewed Apr 7, 2023

View reviewed changes

dmcilvaney and others added 4 commits April 7, 2023 11:10

Update toolkit/docs/building/dedicated_guides/build_images.md

a03022e

Co-authored-by: rlmenge <rlmenge@gmail.com>

Apply suggestions from code review

3e78e79

Co-authored-by: rlmenge <rlmenge@gmail.com>

Feedback

ebf2830

Merge branch 'damcilva/2.0/docs/developer_guide_v2' of github.com:dmc…

865d57e

…ilvaney/CBL-Mariner into damcilva/2.0/docs/developer_guide_v2

dmcilvaney marked this pull request as ready for review April 7, 2023 18:48

dmcilvaney requested review from a team as code owners April 7, 2023 18:48

dmcilvaney mentioned this pull request Apr 7, 2023

Add QUICKBUILD flags for fast auto build #5199

Merged

12 tasks

Feedback

479bf45

PawelWMS reviewed Apr 7, 2023

View reviewed changes

christopherco requested changes Apr 8, 2023

View reviewed changes

mfrw reviewed Apr 9, 2023

View reviewed changes

toolkit/docs/building/building.md Show resolved Hide resolved

dmcilvaney mentioned this pull request Apr 10, 2023

Add a script to update manifest files from pkg repo #5251

Closed

12 tasks

htaubenfeld reviewed Apr 10, 2023

View reviewed changes

dmcilvaney and others added 3 commits April 10, 2023 14:32

Apply suggestions from code review 1

d0cab91

Co-authored-by: Christopher Co <35273088+christopherco@users.noreply.github.com> Co-authored-by: htaubenfeld <htaubenfeld@microsoft.com>

Apply suggestions from code review 2

9cfd1ad

Co-authored-by: Christopher Co <35273088+christopherco@users.noreply.github.com> Co-authored-by: htaubenfeld <htaubenfeld@microsoft.com>

Apply suggestions from code review 3

becef07

Co-authored-by: htaubenfeld <htaubenfeld@microsoft.com>

dmcilvaney commented Apr 10, 2023

View reviewed changes

toolkit/docs/building/building.md Outdated Show resolved Hide resolved

dmcilvaney and others added 13 commits April 10, 2023 15:34

Apply suggestions from code review

3e9fb66

Co-authored-by: Christopher Co <35273088+christopherco@users.noreply.github.com>

Apply suggestions from code review

14e34bc

Co-authored-by: Christopher Co <35273088+christopherco@users.noreply.github.com>

Address feedback

aaacbdd

Remove references to specific branches, use '-'

9afe93a

Rename QUICKREBUILD to QUICK_REBUILD

30d0507

Feedback from GPT

e6adefc

Mention CLEAN_TOOLCHAIN_CONTAINERS

4f71ab5

Revert "Fixup"

ed7e340

This reverts commit e82e0be.

Revert "Move REBUILD_TOOLS and USE_CCACHE"

737119e

This reverts commit b64a58b.

Revert "Update toolchain verify output to be more accurate"

684d227

This reverts commit 496c276.

Revert "Rename to QUICKREBUILD"

f30a22a

This reverts commit 96c09a1.

Revert "Add QUICKBUILD flags for fast auto build"

e8c763b

This reverts commit 62a0251.

Merge remote-tracking branch 'upstream/main' into damcilva/2.0/docs/d…

519346c

…eveloper_guide_v2

reorder initial readme entries

f06265f

tobiasb-ms reviewed May 12, 2023

View reviewed changes

dmcilvaney added 2 commits May 12, 2023 10:42

Fix typos in build_packages example

c8cb57c

Another typo

abaca93

SeanDougherty reviewed Jun 2, 2023

View reviewed changes

Feedback

40aa4fe

trungams reviewed Jun 9, 2023

View reviewed changes

dmcilvaney mentioned this pull request Sep 11, 2023

Add help target to toolkit Makefile #6200

Merged

12 tasks

PawelWMS requested a review from a team as a code owner December 12, 2024 00:28

dmcilvaney mentioned this pull request May 19, 2025

Update build documentation with latest best-practices #13828

Open

Copilot AI mentioned this pull request May 19, 2025

Update build documentation with quick build optimization flags #13829

Draft


		######## QUICKREBUILD AUTO CONFIGURE ########

		# The QUICKREBUILD* flags are special flags that will try to build the toolchain and packages as quickly as possible. They will

	Once you have confirmed your change builds and functions as expected, consider whether it should be added to the core repo, [CBL-Mariner](https://github.com/microsoft/CBL-Mariner). Please see our [building instructions](toolkit/README.md) for tutorials and build guides. Please adhere to the [Pull Request guidelines](pull-request-guidelines) when contributing.
	Once you have confirmed your change builds and functions as expected, consider whether it should be added to the core repo, [CBL-Mariner](https://github.com/microsoft/CBL-Mariner). Please see our [building instructions](toolkit/README.md) for tutorials and build guides. Please adhere to the [Pull Request guidelines](#pull-request-guidelines) when contributing.


		### [CBL-MarinerTutorials](https://github.com/microsoft/CBL-MarinerTutorials)

		The [CBL-MarinerTutorials](https://github.com/microsoft/CBL-MarinerTutorials) repo includes several guides for starting with CBL-Mariner images. The full documentation above also links to it where relaxant.

	### Boot and Sign-In to your VHD
	### Boot and Sign-In to your VHD(X)

Damcilva/2.0/docs/developer guide v2 #5218

Are you sure you want to change the base?

Damcilva/2.0/docs/developer guide v2 #5218

Uh oh!

Conversation

dmcilvaney commented Apr 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Checklist

Summary

Change Log

Does this affect the toolchain?

Uh oh!

rlmenge left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dmcilvaney commented Apr 7, 2023

Uh oh!

aadhar-agarwal commented Apr 7, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christopherco left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

htaubenfeld left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dmcilvaney commented Apr 17, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dmcilvaney commented Apr 4, 2023 •

edited

Loading