Clarify Docker build is just one option (was: build SOF fail with docker)

[Rogety]

Transferred from sof to sof-docs, see November 18th comment below from @greg-intel why.

Describe the bug I run ./docker-build.sh in .../sof_buiilder directory the mirror http://isl.gforge.inria.fr/ is down Then I stuck in downloading isl-0.19.tar.xz

the mirror http://isl.gforge.inria.fr/ is down So I change mirror https://libisl.sourceforge.io , it can work but the cnofig file in SOF project should be change, also. When I git branch SOF project, the script also stuck here.

To Reproduce I follow the instructions in SOF documentation

SOF_WORKSPACE=~/work/sof
mkdir -p "$SOF_WORKSPACE"
cd "$SOF_WORKSPACE"
git clone --recurse-submodules https://github.com/thesofproject/sof.git
cd "${SOF_WORKSPACE}"/sof/scripts/docker_build/sof_qemu
./docker-build.sh
cd "${SOF_WORKSPACE}"/sof/scripts/docker_build/sof_builder
./docker-build.sh <------ stuck here 

Reproduction Rate always

Expected behavior It should be work

Impact I can not start my SOF project

Environment

Screenshots or console output

# log 
[INFO ]  Performing some trivial sanity checks
[INFO ]  Build started 20211116.004925
[INFO ]  Building environment variables
[INFO ]  =================================================================
[INFO ]  Retrieving needed toolchain components' tarballs
[ERROR]    isl: download failed
[ERROR]   
[ERROR]  >>
[ERROR]  >>  Build failed in step 'Retrieving needed toolchain components' tarballs'
[ERROR]  >>        called in step '(top-level)'
[ERROR]  >>

# relative script in Dockerfile
ARG GITHUB_SOF=https://github.com/thesofproject
ARG XT_OVERLAY_REPO=$GITHUB_SOF/xtensa-overlay.git
ARG CT_NG_REPO=$GITHUB_SOF/crosstool-ng.git
# build cross compiler
USER sof
RUN cd /home/sof && \
    git clone $CLONE_DEFAULTS --branch sof-gcc10.2 $XT_OVERLAY_REPO && \
    cd xtensa-overlay && cd ../ && \
    git clone $CLONE_DEFAULTS --branch sof-gcc10x $CT_NG_REPO && \
    mkdir -p /home/sof/work/ && \
    cd crosstool-ng && \
    ./bootstrap && ./configure --prefix=`pwd` && make && make install && \
    for arch in byt hsw apl cnl imx imx8m imx8ulp rn; do \
        cp config-${arch}-gcc10.2-gdb9 .config && \

[lgirdwood]

@greg-intel are you able to reproduce since you are currently validating the SDK. @marc-hb any impact for CI ?

[juimonen]

@Rogety you want to build the docker image yourself (are you perhaps modifying it)? or just: "docker pull thesofproject/sof" to get the pre-built image and start to compile sof...

Anyway agreed that the image building should also work.

[marc-hb]

@Rogety can you test tentative fix https://github.com/thesofproject/crosstool-ng/pull/11 ?

[marc-hb]

Wait, one of the main purposes of the Docker image is to provide the already built toolchain(s) so you do NOT have to build them.

Either you don't build the toolchain, or you don't use the Docker image. I don't see why you're building the toolchain(s) that are already built in the image. Have another look at the documentation.

[Rogety]

I found script stuck here

for arch in byt hsw apl cnl imx imx8m imx8ulp rn; do \
        cp config-${arch}-gcc10.2-gdb9 .config && \

I fond the reason is that

# config-byt-gcc10.2-gdb9  
CT_ISL_MIRRORS="http://isl.gforge.inria.fr"  

many config file besides config-byt-gcc10.2-gdb9 in crosstool-ng in thesofproject should be modify.

I am newcomer in my company, and I will take over audio driver to verify board in the Chromium-OS project So, I am studying SOF documentations and follow these instructions and trying to build SOF

@juimonen I guess I just need to get the pre-built image and start to compile sof... @marc-hb I try another way to setup my environment form the document "Build toolchains and SOF from sources" , I encountered another problem in 'aclocal' , I am not farmiliar with that , so I choose Docker to set up my environment.

[marc-hb]

many config file besides config-byt-gcc10.2-gdb9 in crosstool-ng in thesofproject should be modify.

https://github.com/thesofproject/crosstool-ng/pull/11

I am not farmiliar with that , so I choose Docker to set up my environment.

The Docker image is already setup: do not rebuild the toolchains that are already built in. Don't mix up the two distinct sections in the documentation.

[Rogety]

@man-hb OK, thank you.

[marc-hb]

The Docker image is already setup: do not rebuild the toolchains that are already built in. Don't mix up the two distinct sections in the documentation.

@greg-intel did you find a documentation issue here?

[greg-intel]

Yes, I think step four "Get a Docker image with the SOF build environment" under "Set up docker" doesn't split the approaches into distinct enough sections.

[marc-hb]

Transferring this to sof-docs

[marc-hb]

I think I found why the doc is confusing, it comes from a recent change https://github.com/thesofproject/sof-docs/pull/382/files Compare the doc before versus after it:

• BEFORE: https://github.com/thesofproject/sof-docs/blob/65d9f9a8~1/getting_started/build-guide/build-with-docker.rst
• AFTER: https://github.com/thesofproject/sof-docs/blob/65d9f9a8/getting_started/build-guide/build-with-docker.rst

BEFORE was EITHER pull section OR build section

Building the container from DockerFile will take more than 2 hours, so we recommend using the pre-built image.

• Pull Docker image (EITHER section) (explain pull)
• Build Docker image (OR section) (explain build)

But AFTER now looks more like a sequence because it's now a list.

@Rogety would you have understood BEFORE differently?

@anton-intel can you please partly revert or rework your #382?

[anton-intel]

@marc-hb, @Rogety, a bullleted list indicates a user choice (either or), a numbered list - a sequence of steps.

Would the following change work better? Add Option 1 and Option 2 to the list. Move the note about building the container to Option 2 so that it does not between the into sentence and the choices...

To easily build SOF binaries, we need a Docker image containing all of the cross-compiler and build environment dependencies. We can either build a Docker image from a DockerFile or pull an image binary from Docker Hub:

• Option 1. Pull the Docker image ...

• Option 2. Build a Docker image ...

  Note: Building the container from DockerFile will take more than 2 hours, so we recommend using the pre-built image (Option 1).

[greg-intel]

I think that's much clearer. Labeling them with Option 1/2 implies exclusion.

[paulstelian97]

Option 1/Option 2 works. I'd have also suggested saying "Either of the following" or "Exactly one of the following" before the list.

[anton-intel]

I added PR #388 to update the topic.

[greg-intel]

Closing this issue, as the related PR #388 has been merged.