Created attachment 1693 [details] documentation.conf After some testing, we concluded that we should provide task descriptions in Toaster, since people don't necessarily know what each task does. The descriptions will go in documentation.conf, together with the variable descriptions. PaulE has put together a list of tasks we should describe. From that list, we are missing descriptions for: do_bootimg do_bundle_initramfs do_checkuri do_checkuriall do_clean do_cleanall do_cleansstate do_compile_kernelmodules do_deploy do_fetchall do_generate_qt_config_file do_kernel_checkout do_kernel_configcheck do_kernel_configme do_kernel_link_vmlinux do_package_index do_package_write_tar do_populate_sdk do_rm_work do_rm_work_all do_rootfs do_savedefconfig do_sizecheck do_spdx do_strip do_testimage do_testimage_auto do_uboot_mkimage do_validate_branches do_vmdkimg And I've been able to gather descriptions for: do_build[doc] = "Default task for a recipe - depends upon all other normal tasks required to 'build' a recipe" do_compile[doc] = "This task compiles the source in the compilation directory" do_compile_ptest_base[doc] = "This task compiles the test suite included in the package (if any)" do_configure[doc] = "This task configures the source by enabling and disabling any build-time and configuration options for the software being built" do_configure_ptest_base[doc] = "This task configures the test suite included in the package (if any)" do_fetch[doc] = "This task fetches the source code" do_install[doc] = "This task copies files from the compilation directory to a holding area" do_install_ptest_base[doc] = "This task copies the test suite files from the compilation directory to a holding area" do_package[doc] = "This task analyzes the content of the holding area and splits it into subsets based on available packages and files" do_package_write[doc] = "This task creates the actual packages and places them in the Package Feed area" do_package_write_deb[doc] = "This task creates the actual deb packages and places them in the Package Feed area" do_package_write_ipk[doc] = "This task creates the actual ipk packages and places them in the Package Feed area" do_package_write_rpm[doc] = "This task creates the actual rpm packages and places them in the Package Feed area" do_packagedata[doc] = "This task creates package metadata used by the build system to generate the final packages" do_patch[doc] = "This task locates patch files and applies them to the source code" do_populate_lic[doc] = "This task writes license information for the recipe for later collection when constructing the image" do_populate_sysroot[doc] = "This task copies a subset of files installed by do_install into the sysroot in order to make them available to other recipes" do_unpack[doc] = "This task unpacks the source code into a working directory" I've attached the documentation.conf file for reference.
Belen, What do I need to do here? Do you want me to scrub these descriptions? One thing you don't need is the "This task" part to start each line. It is unnecessary. Start with the verb.... (e.g. "Compiles the source", "Compiles the test", "Configures the source", etc.). The "(if any)" in do_configure_ptest_base[doc] and do_compile_ptest_base[doc] are misplaced. They should be placed right after the thing they are referring to (i.e. the test suite). The way these are written implies that there might or might not be a package. Or, maybe I am wrong... Is the optional thing here the package and not the test suite? "deb", "rpm", and "ipk" might be better upper-cased. do_populate_lic[doc] = "This task writes license information for the recipe for later collection when constructing the image" might be better written as "Writes license information for the recipe that is collected later when the image is constructed." Scott
Adding Belen.
(In reply to comment #1) > Belen, > > What do I need to do here? Do you want me to scrub these descriptions? Yes. Sorry Scott, I should have explained. We need you to cast an eye over them and edit as needed. I am trying to gather them all. Thanks! One > thing you don't need is the "This task" part to start each line. It is > unnecessary. Start with the verb.... (e.g. "Compiles the source", "Compiles > the test", "Configures the source", etc.). > > The "(if any)" in do_configure_ptest_base[doc] and > do_compile_ptest_base[doc] are misplaced. They should be placed right after > the thing they are referring to (i.e. the test suite). The way these are > written implies that there might or might not be a package. Or, maybe I am > wrong... Is the optional thing here the package and not the test suite? > > "deb", "rpm", and "ipk" might be better upper-cased. > > do_populate_lic[doc] = "This task writes license information for the recipe > for later collection when constructing the image" might be better written as > "Writes license information for the recipe that is collected later when the > image is constructed." > > Scott
Beth has given us an explanation of do_spdx: "do_spdx is a build stage that takes the source code and scans it on a remote FOSSOLOGY server in order to produce an SPDX document."
How about these: do_bootimg[doc] = "Creates a bootable live image" do_bundle_initramfs[doc] = "Combines an initial ramdisk image and kernel together to form a single image" do_checkuri[doc] = "Validates the SRC_URI value" do_checkuriall[doc] = "Validates the SRC_URI value for all recipes required to build a target" do_clean[doc] = "Removes all output files for a target" do_cleanall[doc] = "Removes all output files, shared state cache and downloaded source files for a target" do_cleansstate[doc] = "Removes all output files and shared state cache for a target" do_compile_kernelmodules[doc] = "Compiles loadable modules for the Linux kernel" do_deploy[doc] = "Writes deployable output files to the deploy directory" do_fetchall[doc] = "Fetches all remote sources required to build a target" do_generate_qt_config_file[doc] = "Writes a qt.conf file for building a Qt-based application" do_kernel_checkout[doc] = "Checks out source/meta branches for a linux-yocto style kernel" do_kernel_configcheck[doc] = "Validates the kernel configuration for a linux-yocto style kernel" do_kernel_configme[doc] = "Assembles the kernel configuration for a linux-yocto style kernel" do_kernel_link_vmlinux[doc] = "Creates a symbolic link in arch/$arch/boot for vmlinux kernel images" do_package_index[doc] = "Creates/updates the index in the Package Feed area" do_package_write_tar[doc] = "Creates tar archives for packages and places them in the Package Feed area" do_populate_sdk[doc] = "Creates the file and directory structure for an installable SDK" do_rm_work[doc] = "Removes work files after the build system has finished with them" do_rm_work_all[doc] = "Top-level task for removing work files after the build system has finished with them" do_rootfs[doc] = "Creates the root filesystem (file and directory structure) for an image" do_savedefconfig[doc] = "Creates a minimal Linux kernel configuration file" do_sizecheck[doc] = "Checks the size of the kernel image against KERNEL_IMAGE_MAXSIZE (if set)" do_strip[doc] = "Strips unneeded sections out of the Linux kernel image" do_testimage[doc] = "Boots an image and performs runtime tests within it" do_testimage_auto[doc] = "Boots an image and performs runtime tests within it immediately after the image has been built" do_uboot_mkimage[doc] = "Creates a uImage file from the kernel for the U-Boot bootloader" do_validate_branches[doc] = "Ensures that the source/meta branches are on the locations specified by their SRCREV values for a linux-yocto style kernel" do_vmdkimg[doc] = "Creates a .vmdk image for use with VMware and compatible virtual machine hosts"
Created attachment 1709 [details] documentation.conf
Thanks to Paul and Beth I've collected all task descriptions now. I've also made the corrections Scott suggested and added everything to the attached documentation.conf Scott: would you mind having a final look to the task descriptions in documentation.conf and suggest any necessary changes? Thanks!
(In reply to comment #4) > Beth has given us an explanation of do_spdx: > > "do_spdx is a build stage that takes the source code and scans it on a > remote FOSSOLOGY server in order to produce an SPDX document." Some edits... "A build stage that takes the source code and scans it on a remote FOSSOLOGY server in order to produce an SPDX document." --Scott
(In reply to comment #5) > How about these: > > do_bootimg[doc] = "Creates a bootable live image" > do_bundle_initramfs[doc] = "Combines an initial ramdisk image and kernel > together to form a single image" > do_checkuri[doc] = "Validates the SRC_URI value" > do_checkuriall[doc] = "Validates the SRC_URI value for all recipes required > to build a target" > do_clean[doc] = "Removes all output files for a target" > do_cleanall[doc] = "Removes all output files, shared state cache and > downloaded source files for a target" > do_cleansstate[doc] = "Removes all output files and shared state cache for a > target" > do_compile_kernelmodules[doc] = "Compiles loadable modules for the Linux > kernel" > do_deploy[doc] = "Writes deployable output files to the deploy directory" > do_fetchall[doc] = "Fetches all remote sources required to build a target" > do_generate_qt_config_file[doc] = "Writes a qt.conf file for building a > Qt-based application" > do_kernel_checkout[doc] = "Checks out source/meta branches for a linux-yocto > style kernel" > do_kernel_configcheck[doc] = "Validates the kernel configuration for a > linux-yocto style kernel" > do_kernel_configme[doc] = "Assembles the kernel configuration for a > linux-yocto style kernel" > do_kernel_link_vmlinux[doc] = "Creates a symbolic link in arch/$arch/boot > for vmlinux kernel images" > do_package_index[doc] = "Creates/updates the index in the Package Feed area" > do_package_write_tar[doc] = "Creates tar archives for packages and places > them in the Package Feed area" > do_populate_sdk[doc] = "Creates the file and directory structure for an > installable SDK" > do_rm_work[doc] = "Removes work files after the build system has finished > with them" > do_rm_work_all[doc] = "Top-level task for removing work files after the > build system has finished with them" > do_rootfs[doc] = "Creates the root filesystem (file and directory structure) > for an image" > do_savedefconfig[doc] = "Creates a minimal Linux kernel configuration file" > do_sizecheck[doc] = "Checks the size of the kernel image against > KERNEL_IMAGE_MAXSIZE (if set)" > do_strip[doc] = "Strips unneeded sections out of the Linux kernel image" > do_testimage[doc] = "Boots an image and performs runtime tests within it" > do_testimage_auto[doc] = "Boots an image and performs runtime tests within > it immediately after the image has been built" > do_uboot_mkimage[doc] = "Creates a uImage file from the kernel for the > U-Boot bootloader" > do_validate_branches[doc] = "Ensures that the source/meta branches are on > the locations specified by their SRCREV values for a linux-yocto style > kernel" > do_vmdkimg[doc] = "Creates a .vmdk image for use with VMware and compatible > virtual machine hosts" Paul, I see no changes needed here... Nicely done. Scott
Created attachment 1710 [details] Scrubbed documentation.conf file Complete edit pass for documentation.conf file.
Belen, Apparently when you create a comment in Bugzilla and then add an attachment, the original comment doesn't stick :) So - I will state here that you can do a diff on my previously attached documentation.conf file against what you attached to verify my edits did not mess any meaning up. Thanks, Scott
Thanks for the edits, Scott! It all looks good to me
verified fixed
Reopening
master 54562006c1327c5b99daa4cc05a3ba7e38412da1
Hmm, even though I see these added task descriptions in the "documentation.conf" file, the only descriptions in the actual Toaster database that I see are these: do_package_write do_package_write_deb do_package_write_ipk do_package_write_tar do_rootfs My repo is at 39846ddbce87d26eb68870914bf86a8ce5e86e5c "bitbake: data_smart: Fix caching issue for double remove references", and definitely includes this case's commit c31a0459461cf8f2d0064f00abd27e3d3c76d7bb "documentation.conf: update task descriptions".