Revamp getting started docs

nklayman commented 2 years ago

Revamp getting started docs add page for same device build/test fix issues in ktest setup improve organization of pages

Signed-off-by: Noah Klayman noah.klayman@intel.com

This PR accomplishes three things:

It changes the organization of the getting started section to make it easier to determine which guide to follow.
It adds instructions for building a custom kernel with SOF config so that it can be booted on that same device. This is useful for people without dedicated test hardware who just want to try out the latest code, such as when they are running into issues with new hardware. I validated that these instructions work on a clean Fedora 35 install.
It revamps the ktest setup documentation. This was very out of date and had tons of errors, especially for using Fedora. It has now been validated to work on both Fedora and Ubuntu target devices, from a Ubuntu dev machine (but Fedora should work just fine too).

There are two semi-blocking issues:

~~The same-device docs assume that https://github.com/thesofproject/kconfig/pull/68 is merged.~~
~~ktest.pl has a bug where it doesn't set the KERNEL_VERSION when loading sof-dev.conf the first time it gets run. This results in an invalid configuration when it gets run for the first time, ie:~~ (workaround found)

More info relating to issue 2

Config:

POST_INSTALL = ssh  -o 'ProxyCommand none' $SSH_USER@$MACHINE sudo dracut --hostonly --force /boot/initramfs-${LOCALVERSION}.img ${KERNEL_VERSION}

First run:

ssh  -o 'ProxyCommand none' root@dev-board sudo dracut --hostonly --force /boot/initramfs-test.img  ... [53 seconds] SUCCESS

Subsequent runs:

ssh  -o 'ProxyCommand none' root@dev-board sudo dracut --hostonly --force /boot/initramfs-test.img 5.16.0-rc1test+ ... [30 seconds] SUCCESS

Note that 5.16.0-rc1test+ is not present in the first run. This causes a failed boot.

Update: Found a workaround, see https://github.com/thesofproject/sof-docs/pull/404/files#diff-00b6d5e2ac08bb291487662715996a41a742a9b9b026c0145350cd1151f7fddcR296-R297

marc-hb commented 2 years ago

Is downloading and extracting a zip file significantly faster than git fetch --depth 1, has this been measured? git has very good compression too.

I went ahead and timed both. I cloned with --bare to exclude the extraction time and compare only the network part of the process. git clone --depth 1 needs 20 seconds more than downloading the corresponding zip.

The compression and download speeds are almost exactly the same (it's from the same server after all). However git has this extra step before starting the download:

...
remote: Counting objects: 100% (78892/78892), done.
remote: Compressing objects: 100% (72823/72823), done.                   <======== extra git step. 20 seconds.
remote: Total 78892 (delta 7101), reused 35497 (delta 5264), pack-reused 0
Receiving objects: 100% (78892/78892), 212.29 MiB | 7.55 MiB/s, done.
...

I think saving 20 seconds is really not worth the extra documentation complexity.

plbossart commented 2 years ago

Is downloading and extracting a zip file significantly faster than git fetch --depth 1, has this been measured? git has very good compression too.

I went ahead and timed both. I cloned with --bare to exclude the extraction time and compare only the network part of the process. git clone --depth 1 needs 20 seconds more than downloading the corresponding zip.

The compression and download speeds are almost exactly the same (it's from the same server after all). However git has this extra step before starting the download:
...
remote: Counting objects: 100% (78892/78892), done.
remote: Compressing objects: 100% (72823/72823), done.                   <======== extra git step. 20 seconds.
remote: Total 78892 (delta 7101), reused 35497 (delta 5264), pack-reused 0
Receiving objects: 100% (78892/78892), 212.29 MiB | 7.55 MiB/s, done.
...
I think saving 20 seconds is really not worth the extra documentation complexity.

You overestimate the capabilities of our esteemed users, who are familiar with zip files but don't know what 'git' is. It's a legit option provided by GitHub, I think we should list the steps needed and move on. It's not an architecture discussion, even the --depth 1 is not useful for true developers.

nklayman commented 2 years ago

@marc-hb @ranj063 thanks for the reviews! Unless I missed something, all of your suggestions are either applied, or I left a comment explaining why I left it as-is. Let me know if there are any outstanding issues you still have.

Also, I'm not really sure what this means, @marc-hb could you elaborate a bit more?

Please move the ("proprietary") Github description to the git commit message. Especially important for explaining the "code" changes to configuration files. Plain English changes more rarely need explanations in... plain English :-)

marc-hb commented 2 years ago

I didn't find the time to read everything again but after a quick look I think all my concerns were addressed, thanks!

marc-hb commented 2 years ago

Please move the ("proprietary") Github description to the git commit message

Also, I'm not really sure what this means, @marc-hb could you elaborate a bit more?

I'm not sure how to elaborate... do you know these are different things? Github does not care about commit messages but we do.

Your Github description has a ton of useful information, your commit message is currently 3 lines long. Can you please make a useful git commit message out of the Github description?

plbossart commented 2 years ago

Please move the ("proprietary") Github description to the git commit message

Also, I'm not really sure what this means, @marc-hb could you elaborate a bit more?

I'm not sure how to elaborate... do you know these are different things? Github does not care about commit messages but we do.

Your Github description has a ton of useful information, your commit message is currently 3 lines long. Can you please make a useful git commit message out of the Github description?

@nklayman what @marc-hb is saying is that we want to keep the description of your changes in plain text in the commit message, instead of the nice markup added for the PR. The reason is that we are still based more on git that github, and we won't look at the PR ever again while git log/blame are very useful tools.

marc-hb commented 2 years ago

and we won't look at the PR ever again while git log/blame are very useful tools.

I do look at PRs again when I need it but yes: I doubt many people do that and in any case it's so much more convenient to find the information in git directly.

Also, who knows what forge we'll be using 5 years from now.

nklayman commented 2 years ago

Ahh I see now, I just wasn't sure what you meant by the '("proprietary") Github description.' I've never heard it called that before. I replaced the old commit description with the one I wrote for the PR, should be good now.

marc-hb commented 2 years ago

I just wasn't sure what you meant by the '("proprietary") Github description.' I've never heard it called that before.

Well it was between quotes and parentheses so clearly not the main point.

git is free and open-source, so data in git is forever safe. Github is different.

plbossart commented 2 years ago

@marc-hb can I bother you to take a look at the updated version. We have quite a few people that are asking for directions to install the latest linux kernel PR #3338 and those instructions are urgently needed. Thanks!

lgirdwood commented 2 years ago

@anton-intel over to you now :)

plbossart commented 2 years ago

@anton-intel can we prioritize this, we have a flurry of issues reported by the community and not everyone knows how to build a kernel. We need to publish this PR in the official docs, thanks!

thesofproject / sof-docs

Revamp getting started docs #404

This PR accomplishes three things:

There are two semi-blocking issues: