diff --git a/README.md b/README.md index cd4cd53..b20c979 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ -# Introduction - -The [CBL-Mariner](https://github.com/microsoft/CBL-Mariner) repository provides detailed instructions for building CBL-Mariner from end-to-end. While it is possible to clone CBL-Mariner and build packages or images from that environment, for most users, it is _not the recommended approach_. Usually it is best to work in a smaller, problem focused environment where you can quickly build just what you need, and rely on the fact that the curated CBL-Mariner packages are already available in the cloud. In this way, you can customize an image with your preferred disk layout or adding supplemental packages that CBL-Mariner may not provide. If you are building a product based on CBL-Mariner, you may want your own repository with just the minimal set of packages for your business needs. This repo, the CBL-MarinerTutorials repo, provides a basic template for getting started. From here you can create a CBL-Mariner based product (aka a Derivative Image) or you may generate quick experimental or debug builds to try out new ideas. - -When you build an ISO, VHD or VHDX image from this repository, the resulting image will contain additional content unavailable in the CBL-Mariner repo. The CBL-MarinerTutorials repository demonstrates how you can augment CBL-Mariner without forking the CBL-Mariner repository. This repository contains the SPEC file and source for building a simple "Hello World" application. This repository also includes a simple "os-subrelease" package that allows you to add identifying information about your derivative to an /etc/os-subrelease file. +# Introduction + +The [CBL-Mariner](https://github.com/microsoft/CBL-Mariner) repository provides detailed instructions for building CBL-Mariner from end-to-end. While it is possible to clone CBL-Mariner and build packages or images from that environment, for most users, it is _not the recommended approach_. Usually it is best to work in a smaller, problem focused environment where you can quickly build just what you need, and rely on the fact that the curated CBL-Mariner packages are already available in the cloud. In this way, you can customize an image with your preferred disk layout or adding supplemental packages that CBL-Mariner may not provide. If you are building a product based on CBL-Mariner, you may want your own repository with just the minimal set of packages for your business needs. This repo, the CBL-MarinerTutorials repo, provides a basic template for getting started. From here you can create a CBL-Mariner based product (aka a Derivative Image) or you may generate quick experimental or debug builds to try out new ideas. + +> **Note:** For customizing Azure Linux images, we recommend using the [Prism tool](https://github.com/microsoft/azure-linux-image-tools), which is the preferred method for building custom images. Please refer to the [Prism Image Customizer documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html) for details. + +When you build an ISO, VHD or VHDX image from this repository, the resulting image will contain additional content unavailable in the CBL-Mariner repo. The CBL-MarinerTutorials repository demonstrates how you can augment CBL-Mariner without forking the CBL-Mariner repository. This repository contains the SPEC file and source for building a simple "Hello World" application. This repository also includes a simple "os-subrelease" package that allows you to add identifying information about your derivative to an /etc/os-subrelease file. Follow this decision tree to ensure you are using the correct repository for your use case: diff --git a/docs/building/building.md b/docs/building/building.md index a3f0eae..561d0f2 100644 --- a/docs/building/building.md +++ b/docs/building/building.md @@ -1,5 +1,7 @@ # Building +> **Note:** For customizing Azure Linux images, we recommend using the [Prism tool](https://github.com/microsoft/azure-linux-image-tools), which is the preferred method for building custom images. Please refer to the [Prism Image Customizer documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html) for details. The instructions below are still valid but represent the legacy approach for building custom images. + - [Tutorial: Build a Demo VHD or VHDX](#tutorial-build-a-demo-vhd-or-vhdx) - [Build Derivate VHD or VHDX](#build-derivate-vhd-or-vhdx) - [Use Hyper-V to Boot Your Demo Image](#use-hyper-v-to-boot-your-demo-image) diff --git a/docs/getting_started/default_images.md b/docs/getting_started/default_images.md index 3211c89..60c1cf0 100644 --- a/docs/getting_started/default_images.md +++ b/docs/getting_started/default_images.md @@ -1,5 +1,7 @@ # Building +> **Note:** For customizing Azure Linux images, we recommend using the [Prism tool](https://github.com/microsoft/azure-linux-image-tools), which is the preferred method for building custom images. Please refer to the [Prism Image Customizer documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html) for details. The instructions below are still valid but represent the legacy approach for building custom images. + - [Tutorial: Build the default ISO](#tutorial-build-the-default-iso) - [Build ISO](#build-iso) - [Use Hyper-V to Boot Your ISO Installer](#use-hyper-v-to-boot-your-iso-installer) diff --git a/docs/packages/working_with_packages.md b/docs/packages/working_with_packages.md index f8e9f88..d8dcb33 100644 --- a/docs/packages/working_with_packages.md +++ b/docs/packages/working_with_packages.md @@ -1,5 +1,7 @@ # Working with Packages +> **Note:** For customizing Azure Linux images, we recommend using the [Prism tool](https://github.com/microsoft/azure-linux-image-tools), which is the preferred method for building custom images. Please refer to the [Prism Image Customizer documentation](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/README.html) for details. The instructions below are still valid but represent the legacy approach for customizing images with packages. If you're creating custom spec files, please see the [Tutorial: Customize your Image with Unsupported Packages](#tutorial-customize-your-image-with-unsupported-packages) section. + - [Image Config File](#image-config-file) - [File Paths](#file-paths) - [Package Lists](#package-lists)