manual: add QEMU demo to quick start
PATCH v3 1/1 manual: add QEMU demo to quick start
---
OK, I think this is the best way to structure the more general intro to configs and their docs.
docs/manual/quickstart.txt | 65 +++++++++++++++++++++++++++++++++++--- 1 file changed, 60 insertions(+), 5 deletions(-)
docs/manual/quickstart.txt +60 -5
@@ -8,12 +8,67 @@ is no need to be root to configure and use Buildroot. By running all commands as a regular user, you protect your system against packages behaving badly during compilation and installation. -The first step when using Buildroot is to create a configuration. -Buildroot has a nice configuration tool similar to the one you can -find in the http://www.kernel.org/[Linux kernel] or in -http://www.busybox.net/[BusyBox]. +=== Try it out with QEMU -From the buildroot directory, run +If you just want to emulate a simple generic QEMU system to see +Buildroot in action immediately, run from the buildroot directory: + +-------------------- +make qemu_x86_64_defconfig +make BR2_JLEVEL="$(nproc)" +qemu-system-x86_64 \ + -M pc \ + -kernel output/images/bzImage \ + -drive file=output/images/rootfs.ext2,if=virtio,format=raw \ + -append "root=/dev/vda" \ + -net nic,model=virtio \ + -net user +-------------------- + +Once QEMU boots, login with +root+, and you are now left inside a minimal +BusyBox based Linux distribution. + +The initial build can take several minutes to a few hours since we download +and compile GCC, the Linux kernel and other basic system components from +source. + +The QEMU command to use is also documented at: +board/qemu/x86_64/readme.txt+ + +=== Day-to-day workflow + +In your day-to-day workflow, the first step when using Buildroot is to +create a custom configuration. + +If you wish to use an existing configuration as your starting point, +first find the available configs with: + +-------------------- + $ ls configs/ +-------------------- + +If you want to build for the Raspberry Pi 3 for example, run: + +-------------------- + $ make raspberrypi3_64_defconfig +-------------------- + +This command generates a +.config+ file in the root directory. + +Each defconfig is documented under: + +-------------------- + $ board/<config-hyphenated>/readme.txt +-------------------- + +for example: + +-------------------- + $ less board/raspberrypi3-64/readme.txt +-------------------- + +Next, to customize the +.config+, Buildroot has a nice configuration tool +similar to the one you can find in the http://www.kernel.org/[Linux kernel] +or in http://www.busybox.net/[BusyBox]. Run it either with -------------------- $ make menuconfig
Signature · 1 line
2.19.0
PATCH v3 1/1 manual: add QEMU demo to quick start
Hello,
Quoted 4 lines · Ciro Santilli
Signed-off-by Ciro Santilli <[email protected]>---
OK, I think this is the best way to structure the more general intro to configs and their docs.
It seems like you haven't taken into account my previous comment.
Quoted 7 lines
+=== Try it out with QEMU
docs/manual/quickstart.txt +4
-1-From the buildroot directory, run +If you just want to emulate a simple generic QEMU system to see +Buildroot in action immediately, run from the buildroot directory: + +--------------------
docs/manual/quickstart.txt is no need to be root to configure and use Buildroot. By running all · line 26
Quoted 10 lines
docs/manual/quickstart.txt +10
-0+make qemu_x86_64_defconfig +make BR2_JLEVEL="$(nproc)" +qemu-system-x86_64 \ + -M pc \ + -kernel output/images/bzImage \ + -drive file=output/images/rootfs.ext2,if=virtio,format=raw \ + -append "root=/dev/vda" \ + -net nic,model=virtio \ + -net user +--------------------
Please point the user to board/qemu/x86-64/readme.txt instead, don't duplicate the information. And I believe the section should be made more general, and talk about all defconfigs. Maybe a section:
"Quick start on HW platforms or Qemu"
and then describe that we have defconfigs, how to use them, that we have readme files to explain how to use the result of the defconfigs, etc.
Quoted 25 lines
+=== Day-to-day workflow
docs/manual/quickstart.txt +24
-0+ +In your day-to-day workflow, the first step when using Buildroot is to +create a custom configuration. + +If you wish to use an existing configuration as your starting point, +first find the available configs with: + +-------------------- + $ ls configs/ +-------------------- + +If you want to build for the Raspberry Pi 3 for example, run: + +-------------------- + $ make raspberrypi3_64_defconfig +-------------------- + +This command generates a +.config+ file in the root directory. + +Each defconfig is documented under: + +-------------------- + $ board/<config-hyphenated>/readme.txt +--------------------
docs/manual/quickstart.txt is no need to be root to configure and use Buildroot. By running all · line 71
Quoted 10 lines
docs/manual/quickstart.txt +10
-0+ +for example: + +-------------------- + $ less board/raspberrypi3-64/readme.txt +-------------------- + +Next, to customize the +.config+, Buildroot has a nice configuration tool +similar to the one you can find in the http://www.kernel.org/[Linux kernel] +or in http://www.busybox.net/[BusyBox]. Run it either with
I am not sure this section "Day-to-day workflow" is very useful/makes a lot of sense in the context of the Buildroot manual.
Best regards,
Thomas
Signature · 3 lines
Thomas Petazzoni, CTO, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
PATCH v3 1/1 manual: add QEMU demo to quick start
Quoted 11 lines · Thomas Petazzoni
Hello,
Quoted 4 lines · Ciro Santilli
Signed-off-by Ciro Santilli <[email protected]>---
OK, I think this is the best way to structure the more general intro to configs and their docs.It seems like you haven't taken into account my previous comment.
Sorry, which one did I miss?
In any case, if you think kind of intro might be useful, can you make the adjustment that you have in mind and it yourself? I think it would be easier in this case. No need to credit me or anything.
I just highly recommend keeping:
+make qemu_x86_64_defconfig
+make BR2_JLEVEL="$(nproc)"
+qemu-system-x86_64 \
+ -M pc \ + -kernel output/images/bzImage \ + -drive file=output/images/rootfs.ext2,if=virtio,format=raw \ + -append "root=/dev/vda" \ + -net nic,model=virtio \ + -net user
as close as possible to the top of the getting started ;-)
Quoted 75 lines
Quoted 7 lines
+=== Try it out with QEMU
docs/manual/quickstart.txt +4
-1-From the buildroot directory, run +If you just want to emulate a simple generic QEMU system to see +Buildroot in action immediately, run from the buildroot directory: + +--------------------docs/manual/quickstart.txt is no need to be root to configure and use Buildroot. By running all · line 26
Quoted 10 lines
docs/manual/quickstart.txt +10
-0+make qemu_x86_64_defconfig +make BR2_JLEVEL="$(nproc)" +qemu-system-x86_64 \ + -M pc \ + -kernel output/images/bzImage \ + -drive file=output/images/rootfs.ext2,if=virtio,format=raw \ + -append "root=/dev/vda" \ + -net nic,model=virtio \ + -net user +--------------------Please point the user to
board/qemu/x86-64/readme.txtinstead, don't duplicate the information. And I believe the section should be made more general, and talk about all defconfigs. Maybe a section:"Quick start on HW platforms or Qemu"
and then describe that we have defconfigs, how to use them, that we have readme files to explain how to use the result of the defconfigs, etc.
Quoted 25 lines
+=== Day-to-day workflow
docs/manual/quickstart.txt +24
-0+ +In your day-to-day workflow, the first step when using Buildroot is to +create a custom configuration. + +If you wish to use an existing configuration as your starting point, +first find the available configs with: + +-------------------- + $ ls configs/ +-------------------- + +If you want to build for the Raspberry Pi 3 for example, run: + +-------------------- + $ make raspberrypi3_64_defconfig +-------------------- + +This command generates a +.config+ file in the root directory. + +Each defconfig is documented under: + +-------------------- + $ board/<config-hyphenated>/readme.txt +--------------------docs/manual/quickstart.txt is no need to be root to configure and use Buildroot. By running all · line 71
Quoted 10 lines
docs/manual/quickstart.txt +10
-0+ +for example: + +-------------------- + $ less board/raspberrypi3-64/readme.txt +-------------------- + +Next, to customize the +.config+, Buildroot has a nice configuration tool +similar to the one you can find in the http://www.kernel.org/[Linux kernel] +or in http://www.busybox.net/[BusyBox]. Run it either withI am not sure this section "Day-to-day workflow" is very useful/makes a lot of sense in the context of the Buildroot manual.
Best regards,
Thomas
--
Thomas Petazzoni, CTO, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
PATCH v3 1/1 manual: add QEMU demo to quick start
Ciro,
Quoted 33 lines · Ciro Santilli
Quoted 11 lines · Thomas Petazzoni
Hello,
Quoted 4 lines · Ciro Santilli
Signed-off-by Ciro Santilli <[email protected]>---
OK, I think this is the best way to structure the more general intro to configs and their docs.It seems like you haven't taken into account my previous comment.
Sorry, which one did I miss?
In any case, if you think kind of intro might be useful, can you make the adjustment that you have in mind and it yourself? I think it would be easier in this case. No need to credit me or anything.
I just highly recommend keeping:
docs/manual/quickstart.txt +9
-0+make qemu_x86_64_defconfig +make BR2_JLEVEL="$(nproc)" +qemu-system-x86_64 \ + -M pc \ + -kernel output/images/bzImage \ + -drive file=output/images/rootfs.ext2,if=virtio,format=raw \ + -append "root=/dev/vda" \ + -net nic,model=virtio \ + -net user
Quoted 1 line
as close as possible to the top of the getting started ;-)
I'm with Thomas on this one, the readme.txt for each qemu board are
not the same to invoke QEMU for the different architectures. If
anything note that the Buildroot provided qemu configurations target a number of architectures and that for each of those there is an example qemu launch command found in board/qemu/<arch>/readme.txt
By referencing the existing readme.txt we keep the manual easier to maintain if there for some reason becomes a reason to update the qemu launch command.
Quoted 61 lines
Quoted 61 lines
Quoted 8 lines
+=== Try it out with QEMU
docs/manual/quickstart.txt +4
-1-From the buildroot directory, run +If you just want to emulate a simple generic QEMU system to see +Buildroot in action immediately, run from the buildroot directory: + +--------------------docs/manual/quickstart.txt is no need to be root to configure and use Buildroot. By running all · line 26
Quoted 10 lines
docs/manual/quickstart.txt +10
-0+make qemu_x86_64_defconfig +make BR2_JLEVEL="$(nproc)" +qemu-system-x86_64 \ + -M pc \ + -kernel output/images/bzImage \ + -drive file=output/images/rootfs.ext2,if=virtio,format=raw \ + -append "root=/dev/vda" \ + -net nic,model=virtio \ + -net user +--------------------Please point the user to
board/qemu/x86-64/readme.txtinstead, don't duplicate the information. And I believe the section should be made more general, and talk about all defconfigs. Maybe a section:"Quick start on HW platforms or Qemu"
and then describe that we have defconfigs, how to use them, that we have readme files to explain how to use the result of the defconfigs, etc.
Quoted 31 lines
+=== Day-to-day workflow
docs/manual/quickstart.txt +30
-0+ +In your day-to-day workflow, the first step when using Buildroot is to +create a custom configuration. + +If you wish to use an existing configuration as your starting point, +first find the available configs with: + +-------------------- + $ ls configs/ +-------------------- + +If you want to build for the Raspberry Pi 3 for example, run: + +-------------------- + $ make raspberrypi3_64_defconfig +-------------------- + +This command generates a +.config+ file in the root directory. + +Each defconfig is documented under: + +-------------------- + $ board/<config-hyphenated>/readme.txt +-------------------- + +for example: + +-------------------- + $ less board/raspberrypi3-64/readme.txt +--------------------
Quoted 8 lines
Quoted 8 lines
docs/manual/quickstart.txt is no need to be root to configure and use Buildroot. By running all · line 71
Quoted 4 lines
docs/manual/quickstart.txt +4
-0+ +Next, to customize the +.config+, Buildroot has a nice configuration tool +similar to the one you can find in the http://www.kernel.org/[Linux kernel] +or in http://www.busybox.net/[BusyBox]. Run it either withI am not sure this section "Day-to-day workflow" is very useful/makes a lot of sense in the context of the Buildroot manual.
Ciro, maybe there is a good blog or forum where an example use case could be posted (or improved) capturing the day to day targeting of a Raspberrypi using buildroot? Looks like there are a few out there.
https://www.google.com/search?q=buildroot+raspberry+pi&oq=buildroot+ras&aqs=chrome.0.0j69i57j69i61j0l3.2031j1j7&sourceid=chrome&ie=UTF-8
Matt
PATCH v3 1/1 manual: add QEMU demo to quick start
Quoted 47 lines · Matthew Weber
Ciro,
Quoted 33 lines · Ciro Santilli
Quoted 11 lines · Thomas Petazzoni
Hello,
Quoted 4 lines · Ciro Santilli
Signed-off-by Ciro Santilli <[email protected]>---
OK, I think this is the best way to structure the more general intro to configs and their docs.It seems like you haven't taken into account my previous comment.
Sorry, which one did I miss?
In any case, if you think kind of intro might be useful, can you make the adjustment that you have in mind and it yourself? I think it would be easier in this case. No need to credit me or anything.
I just highly recommend keeping:
docs/manual/quickstart.txt +9
-0+make qemu_x86_64_defconfig +make BR2_JLEVEL="$(nproc)" +qemu-system-x86_64 \ + -M pc \ + -kernel output/images/bzImage \ + -drive file=output/images/rootfs.ext2,if=virtio,format=raw \ + -append "root=/dev/vda" \ + -net nic,model=virtio \ + -net userQuoted 1 line
as close as possible to the top of the getting started ;-)
I'm with Thomas on this one, the readme.txt for each qemu board are
not the same to invoke QEMU for the different architectures. If
anything note that the Buildroot provided qemu configurations target a number of architectures and that for each of those there is an example qemu launch command found in board/qemu/<arch>/readme.txt
Quoted 4 lines
By referencing the existing readme.txt we keep the manual easier to maintain if there for some reason becomes a reason to update the qemu launch command.
Hi Matt,
It does generate some duplication, but it is fundamental to attract more new users.
People who are browsing several similar alternative projects are drastically more likely to try out your stuff if they can copy three lines from the top of the getting started and see it just do something awesome happen, without following any links.
The duplication of an awesome getting started that just works is the price you have to pay if you want to become more famous through your project.
If you really want to avoid duplicating that line, put it into a separate bash script from the readme.txt of every QEMU, and run that from getting started. That would actually be a good idea.
But up to you of course. I won't be updating this patch further, please modify it to do the update you guys think is best or ignore it ;-)
Quoted 70 lines
Quoted 61 lines
Quoted 61 lines
Quoted 8 lines
+=== Try it out with QEMU
docs/manual/quickstart.txt +4
-1-From the buildroot directory, run +If you just want to emulate a simple generic QEMU system to see +Buildroot in action immediately, run from the buildroot directory: + +--------------------docs/manual/quickstart.txt is no need to be root to configure and use Buildroot. By running all · line 26
Quoted 10 lines
docs/manual/quickstart.txt +10
-0+make qemu_x86_64_defconfig +make BR2_JLEVEL="$(nproc)" +qemu-system-x86_64 \ + -M pc \ + -kernel output/images/bzImage \ + -drive file=output/images/rootfs.ext2,if=virtio,format=raw \ + -append "root=/dev/vda" \ + -net nic,model=virtio \ + -net user +--------------------Please point the user to
board/qemu/x86-64/readme.txtinstead, don't duplicate the information. And I believe the section should be made more general, and talk about all defconfigs. Maybe a section:"Quick start on HW platforms or Qemu"
and then describe that we have defconfigs, how to use them, that we have readme files to explain how to use the result of the defconfigs, etc.
Quoted 31 lines
+=== Day-to-day workflow
docs/manual/quickstart.txt +30
-0+ +In your day-to-day workflow, the first step when using Buildroot is to +create a custom configuration. + +If you wish to use an existing configuration as your starting point, +first find the available configs with: + +-------------------- + $ ls configs/ +-------------------- + +If you want to build for the Raspberry Pi 3 for example, run: + +-------------------- + $ make raspberrypi3_64_defconfig +-------------------- + +This command generates a +.config+ file in the root directory. + +Each defconfig is documented under: + +-------------------- + $ board/<config-hyphenated>/readme.txt +-------------------- + +for example: + +-------------------- + $ less board/raspberrypi3-64/readme.txt +--------------------Quoted 8 lines
Quoted 8 lines
docs/manual/quickstart.txt is no need to be root to configure and use Buildroot. By running all · line 71
Quoted 4 lines
docs/manual/quickstart.txt +4
-0+ +Next, to customize the +.config+, Buildroot has a nice configuration tool +similar to the one you can find in the http://www.kernel.org/[Linux kernel] +or in http://www.busybox.net/[BusyBox]. Run it either withI am not sure this section "Day-to-day workflow" is very useful/makes a lot of sense in the context of the Buildroot manual.
Quoted 5 lines
Ciro, maybe there is a good blog or forum where an example use case could be posted (or improved) capturing the day to day targeting of a Raspberrypi using buildroot? Looks like there are a few out there.
https://www.google.com/search?q=buildroot+raspberry+pi&oq=buildroot+ras&aqs=chrome.0.0j69i57j69i61j0l3.2031j1j7&sourceid=chrome&ie=UTF-8
I have already copied those three lines of code on several Stack Overflow answers :-)
But anything outside of main docs has negligible effect, and inevitably gets outdated.
Quoted 1 line
Matt