Hi Barbara, I reviewed the whole Distro Constructor document, except trying out the 3 examples. I also reviewed the man page. My comments for those are belong. Following these comments, I also tried to answer most of your questions inline.
Comments on the Distro Const document: ------------------------------------------------------- - Page 5, first sentence... "....advanced application developers....". I think that this will make it intimidated for many users. The DC actually is quiet easy to use if you just want to add packages to build your own repo. I think it will be better to just say "application developers". - Page 5, "What is the Distribution Constructor" section, 2nd paragraph, 2nd sentence. * 2nd sentence is now is kinda confusing. I think it is more accurate to say: "These images are bootable and can be used for installation and other purposes". * 3rd and 4th sentence is more accurate to say: "Both ISO and USB images can be easily distributed on the Internet. The ISO image needs to be burned into a CD/DVD before using. The USB image needs to be copied into a USB flash drive using a special Solaris utility". * In the "Note" section, please mention that "usbcopy" is the only thing that can be used to copy the USB image into a USB flash drive. No other utility for copying the USB image will work. - Page 6, second paragraph that start with "For x86 ....". I don't think this paragraph is needed. Not sure what information is being presented. - Page 6, "How does Distribution Constructor Work?", 2nd paragraph. I think it is more accurate to say: "The distribution constructor creates images based on settings specified in a file. This file is the blue print from which every image is built. This blueprint is an XML file called a manifest file. You can manually edit this file to customize the blueprint. A few manifest files used for creating the various images distributed in 2009.06 are included in the distribution constructor package. - Page 6, "How does Distribution Constructor Work?", 3rd paragraph, first sentence It is better to say: "The distribution constructor package also includes a default set of script that makes customization based on the type of image you are going to build. - Page 7, first bullet point. Should be "Name of packages to be included in the image" - Page 7, "Checkpointing options" section * There are many mentions of stop and test the image in this section. It is actually not possible to test the image during the construction process. We provide people to stop and restart so people can examine the content of the image to see whether it is the way they want at any certain time. * 2nd paragraph, it is better to say, "A checkpoint in the build process is created after each finalizer script is executed. Therefore, new checkpoint references will be added as you add new finalizer scripts." - Page 10, "Required Package" section, 2nd paragraph, "The Package Manager.....on the desktop for both the OpenSolaris Live CD and the installed OpenSolaris 2009.06 system". I don't think you should mention Open Solaris Live CD, because people should only run DC on an installed system, not from the Live CD. - Page 11, "Note section," ..., including files in /usr/bin/ManifestRead..." ManifestRead is a file. - Page 13, "Editing the Manifest File" section * first sentence, first paragraph, "...includes a default manifest file".. the SUNWdistro-const actually includes many manifests that are used for creating the various images * second paragraph, ".... the default manifest file is located at ....." Should be, the manifest file used for creating the 2009.06 x86 Live CD is: /usr/share/distro_const/slim_cd/slim_cd_x86.xml * 3rd paragraph, "You must make some edits to this file...." Actually, we can skip this. Nothing in the manifest need to be changed. All the defaults will work. - Page 15, "<finalizer>" description in that table, first sentence ".....and how the constructor calls them". More accurate to say, "the order in which the distribution constructor invokes them" - Page 16, "Using the Finalizer Scripts section". * I think we should include all the AI finalizer scripts * For slim cd, there's one new script: slim_cd/slimcd_gen_cd_content: Generate the list of files that are part of the Slim Live CD image. - Page 17, "Customizing finalizer scripts" section * item 4, should be: "..... of the manifest file, you must specify a checkpoint name that is used for pause the image build ....." - Page 29, 2nd bullet point for "You can use the distro_const command..." * should be: "Build an image, but pause and restart the build as needed in order to examine the content of the image and debug the finalizer scripts during the build process." - Page 29, first note in the "Using checkpointing to create an Image" section, 2nd sentence * In order for the 2nd sentence to flow together with the first one, I think the 2nd sentence should say something along the lines of: "Checkpointing can only be enabled when you specify z ZFS dataset, or a mount point that correlates to a ZFS dataset , as your build area" - Page 33, table 3-3, "distro_const build -l manifest" section. I am not sure whether there's value in listing all the steps here, because we now have 4 different manifests building images that's distributed as 2009.06. So, there's no such thing as the "default" manifest. But if you want to give an example, I suggest you specify the exact name of the manifest the steps come from. For example, the /usr/share/distro_const/slim_cd/slim_cd_x86.xml manifest has the following steps. I just copied and pasted the "-l" output from one of my manifest, so, please ignore the resumable field. Step Resumable Description -------------- --------- ------------- im-pop X Populate the image with packages im-mod X Image area modifications slim-im-mod X Slim CD Image area Modifications br-init X Boot root initialization slim-br-config X Slim CD boot root configuration br-config X Boot root configuration br-arch X Boot root archiving slim-post-mod X Slim CD post bootroot image area modification grub-setup X Grub menu setup post-mod Post bootroot image area modification gen-slim-cont Generate Slim CD image content list iso ISO image creation - The sample manifest file in the appendix has a lot of garbage character. ------------------- Comments on the man page ------------------------ - The name for the slim cd manifest file is changed to slim_cd_x86.xml. - In the paragraph that starts with "See the Distro-Constructor guide at...". The link is release specific. Do we want to do that? You will have to modify it for each release. - The output for "distro_const build -l slim_cd_x86.xml" is changed, see my comment about the user guide above. Barbara.Lundquist at sun.com wrote: > Install gang, > > The distribution constructor docs are available for review. See > * DistroConst.pdf > * distro_const(1M) > at: > http://www.opensolaris.org/os/project/caiman/files/ > > The primary review of these docs should be done by 3/17, although I'll > extent review a second week as needed. > > Tomorrow during install team meetings, I'll bring up the following > review questions. I hope we can assign contacts for me tomorrow to > help me with the various questions below and any others that come up > over the next week. > > Barbara > > Introduction to DC Topic > > -------------------------------- > > 1 - I added a note near the start and in sys req section mentioning > SPARC AI option. Do we need to say more about that in DC doc, other > than pointing to AI doc? > For this, do you mean near the top of page 6? If so, as I don't think it is described accurately. It should say something along the lines of: "Starting with the OpenSolaris 2009.06 release, the Distribution Constructor can be used to build SPARC AI images. SPARC live CD images are not supported by the Distribution Constructor at this time". > 2 - I did alot of writer edits for greater clarity. Topic needs a > technical proofread. > > > SETUP DC Topic > --------------- > > 1 - We need to clarify where to get the images from, will it just be > opensolaris.com for > both x86 and SPARC AI images? > > Get what images? for what? I am not sure what you mean here. > 2 - How much detail should we provide for network access in sys req? > Should we just point to this > topic in the AI docs, where we plan to cover it more in detail? > For network access, I think it is suffice to mention that the machine that you use the DC on can contact the IPS server specified in the manifest. > > 3 - Have I listed any internal files by mistake? > Not that I noticed > 4 - Have any of the system requirements changed? I don't think any system requirements except that people should run the 2009.06 DC on 2009.06, unless you want to get into the small detail on exactly which intermediate build should be used, but I don't think you want to do that, right? If you do, I can provide you with that info. > > > Using DC Topic > -------------- > 1 - I did alot of writer edits for greater clarity, Topic needs a > technical proofread. > > 2 - In manifest, is the checkpoint option for "resume from=" still a > number, not a text value? > All checkpoints are reference by text value only. Which "resume from=" value in the manifest are you talking about? I don't see such a value in the manifest. > 3 - Have we sufficiently answered this question: "How do I > replace/modify/remove specific packages in my distribution without > having to pull all the packages each time I make a change?" You mean, does the 3 example finalizer scripts help to answer the above question? I think those scripts a good starting points for people who they want to do that. > > 4 - Do we need to expand the explanation of the > pkg_repo_addl_authority element of the manifest in order to explain > how to point to repos outside the main Sun repos? Add some examples of > outside-Sun repositories? > > I think this is a great idea. > > (#5 - #10 are SPARC questions) > 5 - What IPS repository should be specified in the manifest file in > order to get SPARC packages from a repository? There's no such thing as a special repo for SPARC packages. Both SPARC and x86 packages live on the same repo. http://pkg.opensolaris.org should work. > 6 - We need to expand the section that describes editing the > repository. We should add some > real-world examples of the various repositories and when they would be > used. > > 7 - How do we need to edit the finalizer scripts section of manifest > file to describe SPARC specifications? > Currently, that section mentions a grub_setup script for > initialization of grub menu... There's a manifest file for building the SPARC image. Perhaps talking about some of the SPARC specific items there? The SPARC specific manifest is: /usr/share/distro_const/auto_install/ai_sparc_image.xml > > 8 - Are there SPARC-specific scripts that are now included in the > default finalizer scripts? > I don't think there's any script that's SPARC only. We support SPARC by modifying a few existing finalizer scripts. > 9 - Are there SPARC packages used either by default or optional that > need to be referenced by the manifest file? There's no SPARC specific packages for build SPARC images using DC. The ai_sparc_image.xml is sufficient to trigger all the sparc specific code in the finalizer scripts. > > 10 - Is there a SPARC impact on boot root information in the manifest > file that need to be mentioned? Yes. In particilar, the "fiocompress" option > > (#11 - 16 are finalizer script questions) > > 11 - We need to explain the purpose of stdout and stderr parameters in > finalizer scripts. "stdout" and "stderr" parameters? Those are not parameters. All stdout and stderr goes to the DC log files. Users can't specify anything special there. > > 12 - We need to define the role of the argslist in finalizer scripts. Not sure why this is needed. > > 13 - In the Adding Packages custom script example, we need a short > paragraph explaining the example, using > the example specifics. > 14 - In the Testing Packages example, we need a short paragraph > explaining the example, using the example specifics. > 15 - In the Adding a SVR4 Package example, we need a short paragraph > explaining the example, using the example specifics. > > 16 - We have complaint that our examples use XML inconsistently. We > need to check that issue. > > (#17 is distro_const/man page question) > > 17 - We need to compare the Distro_const command table to the > distro_const man page and check both the table and the man page for > any discrepancies or improvements. > > (#18 - 20 are general questions) > > 18 - Do we want to add any DC-specific troubleshooting information? I think that's a good idea. You can use the information from troubleshooting section in the TOI page. > 19 - Do we want to continue to point to the CD usage TOI? I think the link to the TOI should be removed, as I no longer maintain it and keep it up to date. > > 20 - We need to replace the sample manifest file in the appendix with > the latest default manifest file. > > > > > > > > > > > > > > >
