The following steps fetch the Yocto layers and repositories
to build Linux images for the APSS (Application Processor SubSystem)
of the Ensemble E7 and E5 series.

The Linux images can be built,
 - In a native Linux Ubuntu 18.04 OS.
 - Inside a Ubuntu 18.04 docker container running in Linux OS.
 - Inside a Ubuntu 18.04 docker container running in MacOS.
 - Inside a Ubuntu 18.04 docker container running in Windows 11 OS.
===================================================================

I. Build Linux images inside a native Ubuntu 18.04 host machine
----------------------------------------------------------------
1. Clone https://github.com/alifsemi/alif_linux-apss-build-setup repository.
   $ git clone https://github.com/alifsemi/alif_linux-apss-build-setup

2. Run the host_setup.sh script to install required packages to build
   Linux images on the host machine before running bitbake commands.
   $ sudo alif_linux-apss-build-setup/scripts/host_setup.sh

3. Fetch the Yocto layers and Ensemble BSP layers for the build using
   the fetch-layers.sh script.
   $ cd alif_linux-apss-build-setup
   $ sh scripts/fetch-layers.sh
   Note:
   1. Run 'sh scripts/fetch-layers.sh update' to get latest changes.
   2. Export REL_TAG with release tag name to build images from a specific tag.
      e.g: export REL_TAG=APSS-v0.5.5

4. Run scripts/setup.sh to setup environment to build Linux images.
   $ source scripts/setup.sh

5. Generate Linux images for the APSS using bitbake.
   $ bitbake alif-tiny-image

6. Use xipImage, bl32.bin, devkit-e7.dtb, and
   alif-tiny-image-devkit-e7.cramfs-xip from the
   tmp/deploy/images/devkit-e7 directory to boot APSS.

II. Build Linux images inside a Ubuntu 18.04 docker container
    running in Linux OS.
----------------------------------------------------------------
1. Install git, docker, and docker.io packages in the native Linux host.
   Please refer to https://docs.docker.com/engine/install/ to install
   docker application specific to the native Linux host distribution.

   For example in the native Ubuntu 20.04 host:
   $ sudo apt install git docker docker.io -y

2. Clone https://github.com/alif_linux-apss-build-setup repository.
   $ git clone https://github.com/alifsemi/alif_linux-apss-build-setup

3. Fetch the Ubuntu 18.04 docker image and install prerequisite packages
   using the build-ubuntu-image.sh script (it takes some time to complete).
   $ ./alif_linux-apss-build-setup/ubuntu-docker/build-ubuntu-image.sh

4. Run the Ubuntu 18.04 docker container using the ubuntu-builder script.
   $ ./alif_linux-apss-build-setup/ubuntu-docker/ubuntu-builder

5. Fetch the Yocto layers and Ensemble BSP layers for the build using
   the fetch-layers.sh script.
   $ cd alif_linux-apss-build-setup
   $ sh scripts/fetch-layers.sh
   Note: Run 'sh scripts/fetch-layers.sh update' to get latest changes.

6. Run scripts/setup.sh to setup environment to build Linux images.
   $ source scripts/setup.sh

7. Generate Linux images for the APSS using bitbake.
   $ bitbake alif-tiny-image

8. Use xipImage, bl32.bin, devkit-e7.dtb, and
   alif-tiny-image-devkit-e7.cramfs-xip from the
   tmp/deploy/images/devkit-e7 to boot APSS.

9. Press Ctrl+D or logout to exit from the Ubuntu 18.04 docker container.

10. Run the ubuntu-builder script again to jump into the
   Ubuntu 18.04 docker container.
   $ ./alif_linux-apss-build-setup/ubuntu-docker/ubuntu-builder

11.The alif_linux-apss-build-setup directory is shared between the native Linux host
   and the Ubuntu 18.04 docker container. So, all files under
   the alif_linux-apss-build-setup directory can also be accessible from the native
   Linux host.

III. Build Linux images inside a Ubuntu 18.04 docker container
     running in MacOS.
---------------------------------------------------------------
1. Install docker desktop package in native MacOS.
   Please refer to
   https://docs.docker.com/desktop/install/mac-install/ to install
   docker desktop application in MacOS running on Intel chip/Apple Silicon.

2. Clone https://github.com/alifsemi/alif_linux-apss-build-setup repository.
   % git clone https://github.com/alifsemi/alif_linux-apss-build-setup

3. Make /opt directory of MacOS shareable with the Ubuntu 18.04
   docker container by navigating to Docker Desktop ->
   Settings -> Resources -> File sharing -> Enter /opt ->
   Apply and restart.
   Note: Increase Virtual disk limit (default is 64GB) if needed by
   navigating to
   Docker Desktop -> Settings -> Resources -> Advanced -> Virtual disk limit.
   Apply and restart.
   Note: Click on 'Re-apply configurations' from Docker Desktop dashboard
   to start Docker Desktop after reboot of Mac host.

4. Allow write permission to /opt directory of MacOS.
   % sudo chmod a+w /opt

5. Replace string 'desktop' with 'osxkeychain' in the ~/.docker/config.json
   file.

6. Fetch the Ubuntu 18.04 docker image and install prerequisite packages
   using the build-ubuntu-image.sh script (it takes some time to complete).
   % cd ./alif_linux-apss-build-setup/mac-docker/
   % ./build-ubuntu-image.sh

7. Run the Ubuntu 18.04 docker image in a new docker container using
   the ubuntu-builder script.
   % ./ubuntu-builder

8. Fetch the Yocto layers and Ensemble BSP layers for the build using
   the fetch-layers.sh script.
   This step is executed inside docker container.
   $ cd $HOME/alif_linux-apss-build-setup
   $ sh scripts/fetch-layers.sh
   Note: Run 'sh scripts/fetch-layers.sh update' to get latest changes.

9.Run scripts/setup.sh to setup environment to build Linux images.
   This step is executed inside the docker container.
   $ source scripts/setup.sh

10.Generate Linux images for the APSS using bitbake.
   This step is executed inside the docker container.
   $ bitbake alif-tiny-image

11.Copy the generated xipImage, bl32.bin, devkit-e7.dtb, and
   alif-tiny-image-devkit-e7.cramfs-xip from the
   tmp/deploy/images/devkit-e7 directory into the /opt directory.
   The images copied to /opt can be accessible from the MacOS.
   Use them for booting.

12.Press Ctrl+D or logout to exit from the Ubuntu 18.04 docker container.

13.Run the run-container script again to jump into the
   Ubuntu 18.04 docker container.
   $ ./run-container

14.Use the setup.sh from $HOME/alif_linux-apss-build-setup/build directory
   to setup environment to build Linux images again.
   This step is executed inside the docker container.
   $ cd $HOME/alif_linux-apss-build-setup/build
   $ source setup.sh

15.Run 'docker rm apss-ubuntu' from the MacOS command
   prompt to remove the docker container.
   CAUTION: This will delete all the data present inside the container.
   % docker rm apss-ubuntu

16.Run 'docker rmi apss/ubuntu-builder:v18.04' from the MacOS
   command prompt to remove already built Ubuntu 18.04
   docker image from the system.
   % docker rmi apss/ubuntu-builder:v18.04
   CAUTION: This will delete custom docker image from the MacOS.

17. Run './clean-container-image' from the native Linux OS command
    prompt to remove both apss-ubuntu container and apss/ubuntu-builder:v18.04
    docker image.

IV. Build Linux images inside a Ubuntu 18.04 docker container
    running in Windows 11 OS.
--------------------------------------------------------------
1. Enable Virtualization Technology in the BIOS.
   a. Restart the physical computer and press appropriate key to
      enter BIOS setup before the primary operating system boots up.
   b. Select,
      - "Advanced BIOS features"
        - "CPU feature"
          - "Virtualization Technology"
            - "Enabled"
   c. Save and Exit

2. Enable Hyper-V, Virtual Machine Platform, and Windows Subsystem for Linux
   features from 'Turn Windows features on or off' section.
   Install Docker Desktop application in Windows 11 OS.

3. Start the Docker Desktop application.

4. Download
   https://github.com/alifsemi/alif_linux-apss-build-setup/archive/refs/heads/main.zip
   file and extract the ZIP file to alif_linux-apss-build-setup directory.

5. Run the Command Prompt application in Windows 11.

6. Change to extracted ./alif_linux-apss-build-setup/windows-docker folder.
   > cd alif_linux-apss-build-setup\windows-docker

7. Build docker image containing Ubuntu 18.04 Linux distribution
   using the docker-container-build.bat script. This script downloads
   the Ubuntu 18.04 Linux distribution, installs dependent packages
   required to build the APSS Linux images using the bitbake tool.
   Building Ubuntu 18.04 docker image takes some time as it fetches
   the packages from the internet.
   > docker-container-build.bat

8. Create and run the Ubuntu 18.04 docker container using
   the docker-container-create.bat script. This script mounts/shares
   directories and files present in the alif_linux-apss-build-setup directory
   onto the /opt directory of the docker container.
   > docker-container-create.bat

9.Switch to the /opt directory inside the Ubuntu 18.04 docker
   container and fetch the Yocto layers and Ensemble BSP layers
   for the build using the fetch-layers.sh.
   $ cd /opt
   $ sh scripts/fetch-layers.sh
   Note: Run 'sh scripts/fetch-layers.sh update' to get latest changes.

10.Run the scripts/setup.sh to setup environment to build Linux images.
   By default, the project's build directory gets created at $HOME/build.
   $ source scripts/setup.sh
   Note: Use the following steps to create different project's build
   directory (build_new) at $HOME/build_new.
   $ source scripts/setup.sh build_new

11.Generate Linux images for the APSS using bitbake.
   $ bitbake alif-tiny-image

12.Copy the generated xipImage, bl32.bin, devkit-e7.dtb, and
   alif-tiny-image-devkit-e7.cramfs-xip from the
   tmp/deploy/images/devkit-e7 directory into the /opt directory.
   The images copied to /opt can be accessible from the Windows 11.
   Use them for booting.

13.Press Ctrl+D or logout to exit from the Ubuntu 18.04 docker container.

14.Run the docker-container-start.bat script again from the Windows 11
   command prompt to jump into the Ubuntu 18.04 docker container.
   > docker-container-start.bat

15.Use the setup.sh from $HOME/build directory to setup environment to build
   Linux images again.
   $ cd $HOME/build
   $ source setup.sh 

16.Run 'docker rm ubuntu' from the Windows 11 command prompt to remove
   the docker container.
   Note: This will delete all the data present inside the container.
   > docker rm ubuntu 

17.Run 'docker rmi apss' from the Windows 11 command prompt to remove
   already built Ubuntu 18.04 image from the system.
   > docker rmi apss