summaryrefslogtreecommitdiffstats
path: root/handbook/extendpoky.xml
diff options
context:
space:
mode:
Diffstat (limited to 'handbook/extendpoky.xml')
-rw-r--r--handbook/extendpoky.xml95
1 files changed, 92 insertions, 3 deletions
diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index f259d2ef0a..fa789d4afb 100644
--- a/handbook/extendpoky.xml
+++ b/handbook/extendpoky.xml
@@ -26,7 +26,15 @@
26 </para> 26 </para>
27 27
28 <para> 28 <para>
29 The simplest way to add a new package is to base it on a similar 29 Before writing a recipe from scratch it is often useful to check
30 someone else hasn't written one already. OpenEmbedded is a good place
31 to look as it has a wider scope and hence a wider range of packages.
32 Poky aims to be compatible with OpenEmbedded so most recipes should
33 just work in Poky.
34 </para>
35
36 <para>
37 For new packages, the simplest way to add a recipe is to base it on a similar
30 pre-existing recipe. There are some examples below of how to add 38 pre-existing recipe. There are some examples below of how to add
31 standard types of packages: 39 standard types of packages:
32 </para> 40 </para>
@@ -556,6 +564,37 @@ BBFILE_PRIORITY_extras = "5"</literallayout>
556 </para> 564 </para>
557 </section> 565 </section>
558 566
567 <section id="usingpoky-changes-supplement">
568 <title>Supplementry Metadata Repositories</title>
569
570 <para>
571 Often when developing a project based on Poky there will be components
572 that are not ready for public consumption for whatever reason. By making
573 use of the collections mechanism and other functionality within Poky, it
574 is possible to have a public repository which is supplemented by a private
575 one just containing the pieces that need to be kept private.
576 </para>
577 <para>
578 The usual approach with these is to create a separate git repository called
579 "meta-prvt-XXX" which is checked out alongside the other meta-*
580 directories included in Poky. Under this directory there can be several
581 different directories such as classes, conf and packages which all
582 function as per the usual Poky directory structure.
583 </para>
584 <para>
585 If extra meta-* directories are found, Poky will automatically add them
586 into the BBPATH variable so the conf and class files contained there
587 are found. If a file called poky-extra-environment is found within the
588 meta-* directory, this will be sourced as the environment is setup,
589 allowing certain configuration to be overridden such as the location of the
590 local.conf.sample file that is used.
591 </para>
592 <para>
593 Note that at present, BBFILES is not automatically changed and this needs
594 to be adjusted to find files in the packages/ directory. Usually a custom
595 local.conf.sample file will be used to handle this instead.
596 </para>
597 </section>
559 598
560 <section id='usingpoky-changes-commits'> 599 <section id='usingpoky-changes-commits'>
561 <title>Committing Changes</title> 600 <title>Committing Changes</title>
@@ -564,8 +603,8 @@ BBFILE_PRIORITY_extras = "5"</literallayout>
564 Modifications to Poky are often managed under some kind of source 603 Modifications to Poky are often managed under some kind of source
565 revision control system. The policy for committing to such systems 604 revision control system. The policy for committing to such systems
566 is important as some simple policy can significantly improve 605 is important as some simple policy can significantly improve
567 usability. The tips below are based on the policy that OpenedHand 606 usability. The tips below are based on the policy followed for the
568 uses for commits to Poky. 607 Poky core.
569 </para> 608 </para>
570 609
571 <para> 610 <para>
@@ -622,6 +661,56 @@ BBFILE_PRIORITY_extras = "5"</literallayout>
622 upgradable packages in all cases. 661 upgradable packages in all cases.
623 </para> 662 </para>
624 </section> 663 </section>
664 <section id='usingpoky-changes-collaborate'>
665 <title>Using Poky in a Team Environment</title>
666
667 <para>
668 It may not be immediately clear how Poky can work in a team environment,
669 or scale to a large team of developers. The specifics of any situation
670 will determine the best solution and poky offers immense flexibility in
671 that aspect but there are some practises that experience has shown to work
672 well.
673 </para>
674
675 <para>
676 The core component of any development effort with Poky is often an
677 automated build testing framework and image generation process. This
678 can be used to check that the metadata is buildable, highlight when
679 commits break the builds and provide up to date images allowing people
680 to test the end result and use them as a base platform for further
681 development. Experience shows that buildbot is a good fit for this role
682 and that it works well to configure it to make two types of build -
683 incremental builds and 'from scratch'/full builds. The incremental builds
684 can be tied to a commit hook which triggers them each time a commit is
685 made to the metadata and are a useful acid test of whether a given commit
686 breaks the build in some serious way. They catch lots of simple errors
687 and whilst they won't catch 100% of failures, the tests are fast so
688 developers can get feedback on their changes quickly. The full builds
689 are builds that build everything from the ground up and test everything.
690 They usually happen at preset times such as at night when the machine
691 load isn't high from the incremental builds.
692 </para>
693
694 <para>
695 Most teams have pieces of software undergoing active development. It is of
696 significant benefit to put these under control of a source control system
697 compatible with Poky such as git or svn. The autobuilder can then be set to
698 pull the latest revisions of these packages so the latest commits get tested
699 by the builds allowing any issues to be highlighted quickly. Poky easily
700 supports configurations where there is both a stable known good revision
701 and a floating revision to test. Poky can also only take changes from specific
702 source control branches giving another way it can be used to track/test only
703 specified changes.
704 </para>
705 <para>
706 Perhaps the hardest part of setting this up is the policy that surrounds
707 the different source control systems, be them software projects or the Poky
708 metadata itself. The circumstances will be different in each case but this is
709 one of Poky's advantages - the system itself doesn't force any particular policy
710 unlike a lot of build systems, allowing the best policy to be chosen for the
711 circumstances.
712 </para>
713 </section>
625 </section> 714 </section>
626 715
627 <section id='usingpoky-modifing-packages'> 716 <section id='usingpoky-modifing-packages'>