2023-06-27_Szczys_Golioth_Zephyr-Manifests.pdf

1、Zephyr Manifest FilesProject Sanity in theEver-changing Zephyr WorldZephyr Manifest FilesProject Sanity in theEver-changing Zephyr Worldtl;dr:Manifest files deliver the bestrevision control for your projectLets talk aboutWhat Zephyrs manifest files areHow they workWhy we should use them in project r

2、eposHow to set up a manifest-based Zephyr applicationNext-step features you should know and useThings that exist outside the scope of this talkszczyschaos.social on Mastodonszczysbsky.social on BlueskyDeveloper Relations Engineer at Golioth15 years of firmware experiencePreviously:Editor in Chief of

3、 HackadayMike SzczysWhat is Golioth?Golioth is an IoT cloud company.We make it easy for hardware engineers toconnect their sensors and devices to the webwithout needing to be a cloud expert.We use Zephyr to support the widest range ofhardware possible.Manifest files are one bigpiece of that puzzle.W

4、hat is a manifest file?What is a manifest file?Manages Project heiarchyRepositories:URL of each repoRepo branch/tag/commitLocal path for checkoutCommitted to a codebaseAdvanced Manifest Features:InheritanceAllow/Block listsGroupingRepo branch/tag/commitWest support for validationApplications Manifes

5、ts Zephyr tree uses Manifests tomanage versions of modules andlibrariesProjects can(and should)followthe same paradigmIf you are not usingmanifests in your projects.Youre DoingZephyr Wrong!Manifest ExamplesMainZephyrManifest:356 Lines./west.ymlBasic StructureProject Based on DefaultProject with Expl

6、icit PathInheritance,allowlist,commandInheritanceEntire nRFConnect SDKManifest(if onallowlist)Use West Init(not Git Clone)west init Get manifest from repositoryClones the top-level repositoryCreates.west/config file with path to top-level manifest and Zephyr locationwest updateParse manifest fileClo

7、ne repositoriesReset repos to specified revisionRecurseRunning west initRunning west initWest Init GotchaOnce youve run west init(even if it fails)youcannot run that command again withoutremoving.west/configRunning west updateWest Update GotchaIf you checkout a new branch/tag/commit yourmanifest fil

8、e might change with that checkout!Run west update religiously.Be compusive about!(Seriously!)Revision Control forYour Zephyr ApplicationsRevision Control forYour Zephyr ApplicationsPlan your applications so theywill always have the buildenvironment present whenthe code was committed.Do Not:Fork the

9、Zephyr tree for your project repoNot Ideal:App repo in Zephyr samples folder It will work,but your app hasno way to track what version ofZephyr should be used for thebuild.Not Ideal:App repo with external Zephyr tree Again,this will work.But what versionof Zephyr is being used for the build?project

10、repoZephyr locationYour project is in the app folder*Zephyr tree/modules in deps folder*Everything is controlled by manifest filesYour project repo consists only of the contents of appThe Right Way*names for app/dep folders can be anythingPros:Zephyr and all modules locked to a known versionYour rep

11、o only tracks your filesZephyr tree/modules in deps folderBuild environment is easily replicated*The Right WayCons:Every Zephyr application stores its own local copyof Zephyr and its modules(2.2 GB and larger)VS Code extensions are playing catch-up*But not the Zephyr SDK and PythonThe Right WayThank

12、 you toAsgeir Stavik HustadSetting Up Your ZephyrApplicationSetting Up Your ZephyrApplicationCreate west.yml with app directoryAdd Zephyr in the depsAdd ModulesLimit modules with allowlistSimple beginningsOur repo will be cloned to an appsubfolder of the folder containing.west/configAdd ZephyrAdds Z

13、ephyr tree to dep/zephyr(but no modules)We Need ModulesThis wont build:Import from ZephyrThis will download ALLZephyr Modules(yuck!)Replacespath:deps/zephyrpath-prefix wasadded by westmanifest v0.8.0RemovedLimit the Zephyr importLimit to only the modulesneeded by this projectwest update with allow-l

14、istOur Zephyr Application TreeNotice.git,this is yourapplication repoWe dont need Git to trackthis,the manifest file in ourapplication repo does this!Customize Your ApplicationsAdd External LibraryProblem:are there anyother modules needed bythe library were adding?Solution:Use themanifest from yourl

15、ibrary to figure this outLibraries:Matching VersionDo these versions worktogether?Yes,because wemanually matched them.But.lets look at themanifest(s)from this libraryLibraries:Matching VersionThis library manifest includesan entry for a tested-working version of ZephyrThis is the librarys manifest f

16、ile:We can use inheritance to alwayspull the correct Zephyr version!Libraries:Matching VersionOriginal ApplicationManifestImproved ApplicationManifestAdd Your Own Helper LibrariesCustom boarddefinitionsOut-of-treedriver libraryWhew,that was a lot!Most things are simple(dont beoverwhelmed)If you get

17、stuck,look for how different Zephyrmodules use manifest tricksOften,things can be done in more than onewayOther Manifest Features YouShould Know About(But we have no time to discuss them)Resolvewest manifest-resolveProduce a single manifest from sourceand all imported manifestsGreat for verifying yo

18、ur modules andlocal pathsFreezewest manifest-freezeProduce a single manifest from sourceand all imported manifestsAll revisions are commit hashes(branches and tags will be converted)GroupsAssociate different modules intogroupsFilter your manifests based on groupsThis is handy during import.likeblock

19、list but for multiple modulesWest Extensionswest West extensions allow you to addyour own custom commands towestThese custom commands can beimported from modulesUser DataPasses data into the projectavailable using westGolioth uses this with Python-basedwest extension(custom command)to apply patches

20、for Twister-basedtestingSummary:Manifests are an important part of revisioncontrolProper use stabilizes the build environmentUseful for out-of-tree boards/drivers/librariesApplication:https:/ Zephyr Docs:https:/golioth.ioManifest Examples:https:/docs.zephyrproject.org/latest/develop/west/manifest.htmlTry Golioth:My name is Mike Szczys,thank you for joining me!