blob: 6ff55e56191b49a22ccfe346371735df9f7819fe [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
3=============================================================
4Transitioning to a custom environment for systems development
5=============================================================
6
7|
8
9.. note::
10
Andrew Geissler09209ee2020-12-13 08:44:15 -060011 So you've finished the :doc:`brief-yoctoprojectqs/index` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -050012 glanced over the document :doc:`what-i-wish-id-known`, the latter contains
13 important information learned from other users. You're well prepared. But
14 now, as you are starting your own project, it isn't exactly straightforward what
15 to do. And, the documentation is daunting. We've put together a few hints to
16 get you started.
17
18#. **Make a list of the processor, target board, technologies, and capabilities
19 that will be part of your project**.
20 You will be finding layers with recipes and other metadata that support these
21 things, and adding them to your configuration. (See #3)
22
23#. **Set up your board support**.
24 Even if you're using custom hardware, it might be easier to start with an
25 existing target board that uses the same processor or at least the same
26 architecture as your custom hardware. Knowing the board already has a
27 functioning Board Support Package (BSP) within the project makes it easier
28 for you to get comfortable with project concepts.
29
30#. **Find and acquire the best BSP for your target**.
Patrick Williams03907ee2022-05-01 06:28:52 -050031 Use the :yocto_home:`Yocto Project Compatible Layers
Andrew Geisslerd1e89492021-02-12 15:35:20 -060032 </software-overview/layers/>` or even the :oe_layerindex:`OpenEmbedded
Patrick Williams03907ee2022-05-01 06:28:52 -050033 Layer Index <>` to find and acquire the best BSP for your
Andrew Geisslerc9f78652020-09-18 14:11:35 -050034 target board. The Yocto Project layer index BSPs are regularly validated. The
35 best place to get your first BSP is from your silicon manufacturer or board
36 vendor – they can point you to their most qualified efforts. In general, for
37 Intel silicon use meta-intel, for Texas Instruments use meta-ti, and so
38 forth. Choose a BSP that has been tested with the same Yocto Project release
39 that you've downloaded. Be aware that some BSPs may not be immediately
40 supported on the very latest release, but they will be eventually.
41
42 You might want to start with the build specification that Poky provides
43 (which is reference embedded distribution) and then add your newly chosen
44 layers to that. Here is the information :ref:`about adding layers
Andrew Geissler517393d2023-01-13 08:55:19 -060045 <dev-manual/layers:Understanding and Creating Layers>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050046
47#. **Based on the layers you've chosen, make needed changes in your
48 configuration**.
49 For instance, you've chosen a machine type and added in the corresponding BSP
Andrew Geissler09036742021-06-25 14:25:14 -050050 layer. You'll then need to change the value of the :term:`MACHINE` variable in your
Andrew Geisslerc9f78652020-09-18 14:11:35 -050051 configuration file (build/local.conf) to point to that same machine
52 type. There could be other layer-specific settings you need to change as
53 well. Each layer has a ``README`` document that you can look at for this type of
54 usage information.
55
56#. **Add a new layer for any custom recipes and metadata you create**.
57 Use the ``bitbake-layers create-layer`` tool for Yocto Project 2.4+
58 releases. If you are using a Yocto Project release earlier than 2.4, use the
59 ``yocto-layer create`` tool. The ``bitbake-layers`` tool also provides a number
60 of other useful layer-related commands. See
Andrew Geissler517393d2023-01-13 08:55:19 -060061 :ref:`dev-manual/layers:creating a general layer using the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050062 \`\`bitbake-layers\`\` script` section.
63
64#. **Create your own layer for the BSP you're going to use**.
65 It is not common that you would need to create an entire BSP from scratch
66 unless you have a *really* special device. Even if you are using an existing
67 BSP, :ref:`create your own layer for the BSP <bsp-guide/bsp:creating a new
68 bsp layer using the \`\`bitbake-layers\`\` script>`. For example, given a
69 64-bit x86-based machine, copy the conf/intel-corei7-64 definition and give
70 the machine a relevant name (think board name, not product name). Make sure
71 the layer configuration is dependent on the meta-intel layer (or at least,
72 meta-intel remains in your bblayers.conf). Now you can put your custom BSP
73 settings into your layer and you can re-use it for different applications.
74
75#. **Write your own recipe to build additional software support that isn't
76 already available in the form of a recipe**.
77 Creating your own recipe is especially important for custom application
78 software that you want to run on your device. Writing new recipes is a
79 process of refinement. Start by getting each step of the build process
80 working beginning with fetching all the way through packaging. Next, run the
81 software on your target and refine further as needed. See :ref:`Writing a New
Andrew Geissler517393d2023-01-13 08:55:19 -060082 Recipe <dev-manual/new-recipe:writing a new recipe>` in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050083 Yocto Project Development Tasks Manual for more information.
84
85#. **Now you're ready to create an image recipe**.
86 There are a number of ways to do this. However, it is strongly recommended
Andrew Geissler615f2f12022-07-15 14:00:58 -050087 that you have your own image recipe --- don't try appending to existing image
Andrew Geisslerc9f78652020-09-18 14:11:35 -050088 recipes. Recipes for images are trivial to create and you usually want to
89 fully customize their contents.
90
91#. **Build your image and refine it**.
92 Add what's missing and fix anything that's broken using your knowledge of the
Andrew Geissler09209ee2020-12-13 08:44:15 -060093 :ref:`workflow <sdk-manual/extensible:using \`\`devtool\`\` in your sdk
Andrew Geisslerc9f78652020-09-18 14:11:35 -050094 workflow>` to identify where issues might be occurring.
95
96#. **Consider creating your own distribution**.
97 When you get to a certain level of customization, consider creating your own
98 distribution rather than using the default reference distribution.
99
100 Distribution settings define the packaging back-end (e.g. rpm or other) as
101 well as the package feed and possibly the update solution. You would create
102 your own distribution in a new layer inheriting from Poky but overriding what
103 needs to change for your distribution. If you find yourself adding a lot of
104 configuration to your local.conf file aside from paths and other typical
105 local settings, it's time to :ref:`consider creating your own distribution
Andrew Geissler517393d2023-01-13 08:55:19 -0600106 <dev-manual/custom-distribution:creating your own distribution>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500107
108 You can add product specifications that can customize the distribution if
109 needed in other layers. You can also add other functionality specific to the
110 product. But to update the distribution, not individual products, you update
111 the distribution feature through that layer.
112
113#. **Congratulations! You're well on your way.**
114 Welcome to the Yocto Project community.
115
116.. include:: /boilerplate.rst