Development Manual Rework - Revision history

Tim Orling at 04:31, 14 July 2017

2017-07-14T04:31:34Z

← Older revision		Revision as of 04:31, 14 July 2017
Line 130:		Line 130:

	This whole section is about various workflows. The information is a mix of concepts, high-level workflow steps, and various details associated with the flows. The chapter is now gone from the dev-manual. I took all conceptual information out and it has landed in the ref-manual. I took out all stand-alone sections and set them up as individual sections in the "Common Tasks" chapter. I took the workflows and dropped them into the appropriate other development manuals. Devtool, in particular, now lives in the sdk-manual. The sections on devtool between the dev-manual and the sdk-manual were 99.9% identical. This will fix that Henry bug.		This whole section is about various workflows. The information is a mix of concepts, high-level workflow steps, and various details associated with the flows. The chapter is now gone from the dev-manual. I took all conceptual information out and it has landed in the ref-manual. I took out all stand-alone sections and set them up as individual sections in the "Common Tasks" chapter. I took the workflows and dropped them into the appropriate other development manuals. Devtool, in particular, now lives in the sdk-manual. The sections on devtool between the dev-manual and the sdk-manual were 99.9% identical. This will fix that Henry bug.

			= Tim's input =

			== First Steps for a Real Project (Intermediate) ==

			The two biggest ideas I find missing in teams new to Yocto Project are:
			* Step 1: create a distro layer
			** Add your own branding to it
			** Add your own image recipe and starting adding packages your team needs/wants
			*** When in doubt, '''require''' another base image recipe and then add to it.
			*** Stop adding '''IMAGE_INSTALL_append''' to your '''local.conf''', put it in your new image recipe.
			* Step 2: create one or more application/functional layers
			** '''devtool finish''' all your custom recipes to these layers (unless they are upstream intent)

			I honestly recommend this (usually as a course correction) to every single team with which I engage. It is clearly not intuitive.

			== Layers are like LEGOs(TM)(R) ==
			=== Keep your "git" working directories clean ===
			* Do not create your new layers as children of '''poky'''.
			** Create them as siblings, this way they can work with '''oe-core''' only and also anyone else's layers.
			** Ship your layers as git repos, not a zipped '''poky''' fork.
			* Create your build directories as siblings of '''poky''', not children.
			* Do not force users of your init script (e.g. '''oe-init-build-env''') to conform to your concept of the location for their build directory! '''HUGE PET PEEVE'''. This makes we want to abandon your layer ''immediately''.
			* Do not force users of your distro layer to conform to your concept of what their '''bblayers.conf''' should be. Let them put their layers where they want them to be!
			* Any layer ''should'' be able to be picked up and dropped in line with any other layer and not interfere.
			* Do not assume everyone is using '''poky'''.


			''(TM) and (R) indicate trademarks of the LEGO Group''

Scottrif: /* Notes for Chapter 4 of the dev-manual: */

2017-07-03T22:45:31Z

Notes for Chapter 4 of the dev-manual:

← Older revision		Revision as of 22:45, 3 July 2017
Line 129:		Line 129:
	== Notes for Chapter 4 of the dev-manual: ==		== Notes for Chapter 4 of the dev-manual: ==

	This whole section is about various workflows. The information is a mix of concepts, high-level workflow steps, and various details associated with the flows. ~~I think the entire~~ chapter can pretty much be recast in some conceptual area of the ref-manual. Then, for each type of workflow, we can create a specific task that has some meaningful steps and real examples for use in the dev-manual. These sections in the dev-manual can be referenced from ~~the associated concepts in the ref-manual.~~		This whole section is about various workflows. The information is a mix of concepts, high-level workflow steps, and various details associated with the flows. The chapter is now gone from the dev-manual. I took all conceptual information out and it has landed in the ref-manual. I took out all stand-alone sections and set them up as individual sections in the "Common Tasks" chapter. I took the workflows and dropped them into the appropriate other development manuals. Devtool, in particular, now lives in the sdk-manual. The sections on devtool between the dev-manual and the sdk-manual were 99.9% identical. This will fix that Henry bug.

	~~=== Section 4.1 - "System Development Workflow" ===~~

	~~Introductory material that will live with the subsections for concepts (in the ref-manual) or introductory area for grouped tasks in~~ the dev-manual.

	~~=== Section 4.1.1 - "Developing a Board Support Package (BSP)" ===~~

	~~Although the steps in this section are technically procedural, the level is more conceptual~~. ~~We should move this discussion to the ref-manual and group it under some sort of new "concepts" heading where~~ conceptual information is discussed. That is one idea. Another, is to create a conceptual section in the BSP Guide to hold this information. One thing we have not discussed is the fate of the BSP Guide in regards to the restructuring of the dev-manual to a task-based document. In any case, the current "Developing a Board Support Package (BSP)" section in the dev-manual is out ~~as it stands now. If we want to replace~~ it in the dev-manual with something more concrete, then I suggest a real example that would be in the form of what is on this dated wiki page - https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another.

	~~=== Section 4.1.2 - "Modifying the Kernel" ===~~

	~~The information in this section is very conceptual and does not belong in the dev~~-manual. ~~Solution for this section is similar to what~~ I ~~suggested for the "Developing a Board Support Package (BSP)" section above. However, this is kernel related so perhaps moving this kernel information to the kernel~~-~~dev manual. Again, if we want to have some concrete example in the dev-manual that is based on the conceptual information here, then we create a real example~~ and ~~use that and tie it to specific tasks.~~

	~~=== Section 4.2 - "Application Development Workflow using and SDK" ===~~

	~~This section can go away I think. We have the SDK manual and all it is here~~ in the ~~sdk-manual is a pointer to that manual.~~

	~~=== Section 4.3 -~~ "~~Modifying Source Code~~" ~~===~~

	~~This section is conceptual by nature~~. ~~Again, high-level procedures to support the concepts but~~ I ~~don't think they should be in~~ the ~~dev-manual. Both devtool and Quilt are covered in this section, and both regarding~~ workflows ~~designed to help the user modify source code. The actual need for this introductory stuff in 4.3 depends on really where the devtool~~ and ~~Quilt sections ultimately reside.~~

	~~=== Section 4.3.1 - "Using devtool in Your Workflow" ===~~

	~~These concepts belong in~~ the ~~ref-manual~~. ~~Right now~~, ~~this material is virtually duplicated~~ in ~~the sdk-manual. It should be one area and then any SDK-specific stuff can be captured~~ in the sdk-manual. The ~~section to put this in in~~ the ~~ref~~-manual ~~would be under a "Concepts" heading~~ and ~~then maybe under something like "Workflows".~~

	~~=== Section 4.3.2 - "Using Quilt in Your Workflow" ===~~

	~~These concepts belong in~~ the ref-manual in a new "Workflows" section bundled under some concepts heading. I can see creating an actual example that works and using it as a section in the dev-manual. The conceptual version from the ref-manual ~~can reference into that example.~~

	~~=== Section 4.3.3 - "Finding Temporary Source Code" ===~~

	~~The reason this section is where it is was to support the Quilt workflow~~. If "Finding your Source Code" is a separate enough task to be in the dev-manual, then we can create a set of steps to walk a user through that give creation of some piece of software and maybe a kernel build. They seem to be different based on what you are building unless I am mis-understanding it.

	~~=== Section 4.4 - "Image Development Using Toaster" ===~~

	The reason this section exists is it was a development workflow and bundled in this overarching section. It is pretty much a placeholder and could be removed. There are ample areas where we can mention Toaster as a way of developing an image and then linking to the Toaster manual. ~~If we have a workflow concepts section in the ref-manual, it can be mentioned there as a type of workflow.~~

	~~=== Section 4.5 - "Using a Development Shell" ===~~

	This ~~is another development workflow. We could have a conceptual description in the appropriate area of the ref-manual that would point back to a specific example~~ that ~~is task-based in the dev-manual.~~

	~~=== Section 4.6 - "Using a Development Python Shell" ===~~

	~~This is the final development workflow section. Same stuff applies here as explained in the "Using a Development Shell" section~~.

Scottrif at 20:16, 28 June 2017

2017-06-28T20:16:13Z

← Older revision		Revision as of 20:16, 28 June 2017
Line 79:		Line 79:

	I re-wrote this introductory section to work more tightly with the introductory material of the ref-manual. Also, created a better "Other Information" section to lead the reader to various places of interest. In particular, I am leveraging off the Yocto Project Backgrounders that exist on the YP Website. These backgrounders are probably the best place for an overall introduction to what the YP is supposed to be and do for you.		I re-wrote this introductory section to work more tightly with the introductory material of the ref-manual. Also, created a better "Other Information" section to lead the reader to various places of interest. In particular, I am leveraging off the Yocto Project Backgrounders that exist on the YP Website. These backgrounders are probably the best place for an overall introduction to what the YP is supposed to be and do for you.

			== Notes for Chapter 2 of the dev-manual: ==

			This chapter has been renamed "Getting Started With the Yocto Project". It is going to be a collection of beginning type procedures. It now has "Setting Up the Development Host to Use the Yocto Project", "Working With Yocto Project Source Files", "Performing a Simple Build", and "Using Pre-Built Binaries and QEMU". This last section likely will be moved. I do not know what the importance is we are placing on using pre-built binaries. We pulled the section from the Quick Start a long time ago and this section was the boiled up version that mirrored it in the dev-manual.

			There are two sections that need flushed out that are impacted by the use of CROPS. One, is to set up the system for CROPS, which seems to be the preferred method now. The other is for setting up a native Linux machine, which will cover the distribution compatibilities and the host package stuff.

Henry Bruce: /* Basic "How To" Topics */

2017-06-23T22:29:34Z

Basic "How To" Topics

← Older revision		Revision as of 22:29, 23 June 2017
Line 6:		Line 6:

	== Basic "How To" Topics ==		== Basic "How To" Topics ==
	I plan to structure these, but just a plain list for the time being		I plan to structure these, but just a plain list for the time being. Many of these topics are already documented, but this feels like a better flow that we have just now.
	=== Basic Skills for Systems Developers ===		=== Basic Skills for Systems Developers ===
	* Deal with corporate proxies.		* Deal with corporate proxies.

Henry Bruce: /* Basic Skills for Application Developers */

2017-06-23T22:27:58Z

Basic Skills for Application Developers

@@ Line 28: / Line 28: @@
 * Building an Extensible SDK
 === Basic Skills for Application Developers ===
 = Tracey's Input =

Henry Bruce: /* Basic "How To" Topics */

2017-06-23T22:01:54Z

Basic "How To" Topics

← Older revision		Revision as of 22:01, 23 June 2017
Line 7:		Line 7:
	== Basic "How To" Topics ==		== Basic "How To" Topics ==
	I plan to structure these, but just a plain list for the time being		I plan to structure these, but just a plain list for the time being
			=== Basic Skills for Systems Developers ===
			* Deal with corporate proxies.
			* Add a package to an image
	* Understand the difference between a recipe and package		* Understand the difference between a recipe and package
	* Add a package to an image
	* Build a package by itself and why that's useful		* Build a package by itself and why that's useful
	* Find out what packages are created by a recipe		* Find out what packages are created by a recipe
Line 14:		Line 16:
	* Find out what files are in an image		* Find out what files are in an image
	* Add an ssh server to an image (enable transferring of files to target)		* Add an ssh server to an image (enable transferring of files to target)
	* ~~Deal with corporate proxies~~.		* Anatomy of a recipe
			* How to find recipes (layers.openembedded,org)
	~~More~~ to ~~come~~		* Understand difference between machine and distro settings
			* How to find and use the right BSP (machine) for your hardware
			* Examples of distro features and where to set them.
			* Understanding the task pipeline and executing individual tasks
			* Understand devtool and how it simplifies your workflow
			* Improve build speeds with shared downloads and shared state cache
			* Generate and understand dependency graph
			* Generate and understand bitbake environment
			* Building an Extensible SDK
			=== Basic Skills for Application Developers ===

	= Tracey's Input =		= Tracey's Input =

Scottrif: /* Scott's Input */

2017-06-20T21:28:51Z

Scott's Input

← Older revision		Revision as of 21:28, 20 June 2017
Line 47:		Line 47:

	Scott Rifenbark - This is a good idea. I was thinking of a similar way to deal with this with sort of a decision tree at the end of the YP Quick Start (flowchart for old-schoolers) that would lead the reader down a path based on information they have about what they want to get accomplished. Then, based on how they traverse the tree, we point them to areas they need to use in the manual.		Scott Rifenbark - This is a good idea. I was thinking of a similar way to deal with this with sort of a decision tree at the end of the YP Quick Start (flowchart for old-schoolers) that would lead the reader down a path based on information they have about what they want to get accomplished. Then, based on how they traverse the tree, we point them to areas they need to use in the manual.

			== Notes for Chapter 1 of the dev-manual: ==

			I re-wrote this introductory section to work more tightly with the introductory material of the ref-manual. Also, created a better "Other Information" section to lead the reader to various places of interest. In particular, I am leveraging off the Yocto Project Backgrounders that exist on the YP Website. These backgrounders are probably the best place for an overall introduction to what the YP is supposed to be and do for you.

Scottrif: /* Notes for Chapter 3 of the dev-manual: */

2017-06-20T14:28:19Z

Notes for Chapter 3 of the dev-manual:

← Older revision		Revision as of 14:28, 20 June 2017
Line 51:		Line 51:
	== Notes for Chapter 3 of the dev-manual: ==		== Notes for Chapter 3 of the dev-manual: ==

	This chapter is mostly reference material. The ~~only stuff that I am going to convert~~ to procedures is the ~~various subsections on how to submit a change. Ultimately, the chapter will disappear in~~ the ~~dev~~-manual ~~as I move stuff out of it~~. What ~~does remain will be located somewhere~~ in ~~the dev-manual as tasks. I am not sure just where yet~~.		This chapter was mostly reference material. The entire chapter has been converted now to procedures by pulling out the reference stuff and placing it into the ref-manual. What is left in Chapter 3 are procedures related to setting up a shared YP development environment, submitting a defect, and submitting a change.

	=== Section 3.1 - "Open Source Philosophy" ===		=== Section 3.1 - "Open Source Philosophy" ===

Scottrif: /* Section 3.9 - "How to Submit a Change" */

2017-06-20T14:25:04Z

Section 3.9 - "How to Submit a Change"

← Older revision		Revision as of 14:25, 20 June 2017
Line 87:		Line 87:
	=== Section 3.9 - "How to Submit a Change" ===		=== Section 3.9 - "How to Submit a Change" ===

	~~This~~ section ~~has~~ a ~~lot~~ of ~~potential for "how-to"~~ procedures. I think the whole section can be re-done to be a procedure that walks the reader through the process. I can create some conceptual information that could live in the ref-manual and then have it point back to the processes here in the dev-manual.		I have re-worked this section into a couple of procedures.

	== Notes for Chapter 4 of the dev-manual: ==		== Notes for Chapter 4 of the dev-manual: ==

Scottrif: /* Section 3.2 - "Using the Yocto Project in a Team Environment" */

2017-06-20T14:24:07Z

Section 3.2 - "Using the Yocto Project in a Team Environment"

← Older revision		Revision as of 14:24, 20 June 2017
Line 59:		Line 59:
	=== Section 3.2 - "Using the Yocto Project in a Team Environment" ===		=== Section 3.2 - "Using the Yocto Project in a Team Environment" ===

	~~This section consists of introductory information for team use and provides a bunch of tips and best practices.~~ I have converted this section to a procedure. For now, you can see the first draft at http://www.yoctoproject.org/docs/scott_temp/dev-manual/dev-manual.html#usingpoky-changes-collaborate, which is in a temporary holding area where the published HTML YP documents live. I need more information on this section from the team. Emails are out soliciting input.		I have converted this section to a procedure. I need more information on this section from the team. Emails are out soliciting input.

	=== Section 3.3 - "Source Repositories" ===		=== Section 3.3 - "Source Repositories" ===