Document void-mklive

[anjandev]

I think there should be a user guide for void-mklive describing bootstrapping a void image from start to finish like here:

https://github.com/void-linux/void-mklive/issues/105#issuecomment-586694000

Reasons for better documenting void-mklive from the pov of a user:

• Sometimes when support for a device is very new, there is no image on voidlinux's download page,
• It allows more people to use the lower level tools so they can contribute (see: the excellent documentation for void-packages)

Should the documentation for void-mklive go in this repository or void-docs?

cc: @flexibeast

[Piraty]

it's documentation is in source (and very helpful at that), and an entry point is its README.md That was always enough for me

[Thomashighbaugh]

Agreed the source documentation is rather helpful. Is there not a way that comments in source code can be converted easily into docs like via Lua (though would honestly need tweaking of course, or it would be AwesomeWM current docs disaster its devs are so radically intolerant of criticism about)

[paper42]

Agreed the source documentation is rather helpful

I think we could improve the README, for example:

• add an example of how to generate a rpi4 image - mkrootfs, mkplatformfs and mkimage
• properly document which tools do what (rootfs and platformfs are often confusing)

Sometimes when support for a device is very new, there is no image on voidlinux's download page,

This should also probably be mentioned in the README.

Is there not a way that comments in source code can be converted easily into docs like via Lua

That sounds like a lot of work just to document how a few simple scripts work. People trying to add a new device can read the source (they would have to do it anyway) and look at other similar commits like 388993eb513a7af0bc33bbc57bc0a6ff941778f4.

[bobertlo]

I think we could improve the README, for example:

* add an example of how to generate a rpi4 image - mkrootfs, mkplatformfs and mkimage

* properly document which tools do what (rootfs and platformfs are often confusing)

+1 also the docker images are generated from this repo and have absolutely no mention

it's documentation is in source (and very helpful at that), and an entry point is its README.md That was always enough for me

This attitude is the only reason I never asked to add documentation or asked for help with these scripts. I always got it working but often reinvented some functionality that exists somewhere inside to, for example, get the docker images to actually build from source.

It's fine to not want to personally write documentation but having this attitude towards documentation contribution makes people leave projects.

[ericonr]

I believe docker has been moved to https://github.com/void-linux/void-docker

[bobertlo]

Sorry I'm a little out of date. I'll disable notifications on this repo also. Just my 2 cents on the issue.

[ericonr]

No worries, I agree on importance.

[manfredu]

Agreed the source documentation is rather helpful

I think we could improve the README, for example:

• add an example of how to generate a rpi4 image - mkrootfs, mkplatformfs and mkimage
• properly document which tools do what (rootfs and platformfs are often confusing)

I agree, but I found it easy to figure that out from the README and calling the scripts with -h.

What I didn't find out at all was how to update the kernel and the other parts for the boot partition. It looks like for newer revisions of the rpi4 board updated software from https://github.com/raspberrypi is required. See https://github.com/void-linux/void-mklive/issues/264.

At the moment I'm not able to get my rpi4 up and running with void. :-(

[manfredu]

I probably made the same mistake as mentioned in https://github.com/void-linux/void-mklive/issues/210. Didn't specify rpi4**-musl** for mkplatformfs.sh because -h mentions only rpi4 not rpi4-musl!

After copying the image to the sd card I overwrote 16 files on the boot drive with those from the raspberrypi/firmware repository.

start*.* and fixup*.* from the following commit.

https://github.com/raspberrypi/firmware/commit/165bd7bc5622ee1c721aa5da9af68935075abedd

Commit 165bd7bc by Dom Cobley, 2022-01-06 16:59

I got the idea from the following link: https://community.volumio.org/t/volumio-not-working-on-raspberry-pi-4-rev-1-5-board-start4-elf-not-compatible/53113/11

And now my rpi4 is booting void linux. :-)

[manfredu]

After copying the image to the sd card I overwrote 16 files on the boot drive with those from the raspberrypi/firmware repository.

This should no longer be necessary, see https://github.com/void-linux/void-packages/pull/38958