http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/555f6f65/develop/mkdocs/search_index.json ---------------------------------------------------------------------- diff --git a/develop/mkdocs/search_index.json b/develop/mkdocs/search_index.json index 1f1695e..84d2e36 100644 --- a/develop/mkdocs/search_index.json +++ b/develop/mkdocs/search_index.json @@ -7937,7 +7937,7 @@ }, { "location": "/os/modules/sysinitconfig/sysconfig_error/", - "text": "Validation and Error Messages\n\n\nWith multiple packages defining and overriding system configuration settings, it \nis easy to introduce conflicts and violations that are difficult to find. The \n\nnewt build \ntarget-name\n command validates the setting definitions and value \noverrides for all the packages in the target to ensure a valid and consistent build.\nIt aborts the build when it detects violations or ambiguities between packages.\n\nThe following sections describe the error conditions that newt detects and \nthe error messages that it outputs. For most errors, newt also outputs \nthe \nSetting history\n with the order of package overrides to help \nyou resolve the errors.\n\n\nNote:\n The \nnewt target config \ntarget-name\n command also detects \nerrors and outputs error messages at the top of the command output. \nThe command outputs the package setting definitions and values after it \noutputs the error messages. It is easy to miss the error mes sages at the top. \n\n\nValue Override Violations\n\n\nThe newt tool uses package priorities to resolve override conflicts. It uses \nthe value override from the highest priority package when multiple \npackages override the same setting. Newt checks for the following \noverride violations:\n\n\n\n\nAmbiguity Violation - Two packages of the same priority override a setting with \ndifferent values. And no higher priority package overrides the setting.\n\n\nPriority Violation - A package overrides a setting defined by a package with higher or \nequal priority. \n\n\n\n\nExample: Ambiguity Violation Error Message\n\n\nThe following example shows the error message that newt outputs for an ambiguity violation:\n\n\nError: Syscfg ambiguities detected:\n Setting: LOG_NEWTMGR, Packages: [apps/slinky, apps/splitty]\nSetting history (newest -\n oldest):\n LOG_NEWTMGR: [apps/splitty:0, apps/slinky:1, sys/log/full:0]\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n and \napps /splitty\n packages \nin the split image target both override the same setting with different \nvalues. The \napps/slinky\n package sets the \nsys/log/full\n package \nLOG_NEWTMGR\n \nsetting to 1, and the \napps/splitty\n package sets the setting to 0. The \noverrides are ambiguous because both are \napp\n packages and \nhave the same priority. The following are excerpts of the defintion \nand the two overrides from the \nsyscfg.yml\n files that cause the error:\n\n\n#Package: sys/log/full\nsyscfg.defs:\n LOG_NEWTMGR:\n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n#Package: apps/slinky\nsyscfg.vals:\n LOG_NEWTMGR: 1\n\n#Package: apps/splitty\nsyscfg.vals:\n LOG_NEWTMGR: 0\n\n\n\n\n\nExample: Priority Violation Error Message\n\n\nThe following example shows the error message that newt outputs for a priority violation \nwhere a package tries to change the setting that was defined by another package at \nthe same priority lev el:\n\n\nError: Priority violations detected (Packages can only override settings defined by packages of lower priority):\n Package: mgmt/newtmgr overriding setting: LOG_NEWTMGR defined by sys/log/full\n\nSetting history (newest -\n oldest):\n LOG_NEWTMGR: [sys/log/full:0]\n\n\n\n\n\nThe above error occurs because the \nmgmt/newtmgr\n lib package \noverrides the \nLOG_NEWTMGR\n setting that the \nsys/log/full\n lib package \ndefines. The following are excerpts of the definition and the override from the \n\nsyscfg.yml\n files that cause this error: \n\n\n#Package: sys/log/full\nsyscfg.defs:\n LOG_NEWTMGR:\n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n#Package: mgmt/newtmgr\nsyscfg.vals:\n LOG_NEWTMGR: 1\n\n\n\n\n\n\n\nFlash Area Violations\n\n\nFor \nflash_owner\n type setting definitions, newt checks \nfor the following violations:\n\n\n\n\nAn undefined flash area is assigned to a setting.\n\n\nA flash area is assigned to multiple settings.\n\n\n\n\nExample: Undefined Flash Area Error Message\n\n\nThe following example shows the error message that newt outputs for an undefined flash area.\n\n\nBuilding target targets/sim_slinky\nError: Flash errors detected:\n Setting REBOOT_LOG_FLASH_AREA specifies unknown flash area: FLASH_AREA_NOEXIST\n\nSetting history (newest -\n oldest):\n REBOOT_LOG_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NOEXIST, sys/reboot:]\n\n\n\n\n\nThe above error occurs because the \nhw/bsp/native\n package assigns the \nundefined \nFLASH_AREA_NOEXIST\n flash area to the \nsys/reboot\n package \n\nREBOOT_LOG_FLASH_AREA\n setting. The following are excerpts of the definition \nand the override from the \nsyscfg.yml\n files that cause the error:\n\n\n#Package: sys/reboot\nsyscfg.defs:\n REBOOT_LOG_FLASH_AREA:\n description: \nFlash Area to use for reboot log.\n\n type: flash_owner\n value:\n\n#Package: hw/bsp/native\nsyscfg.vals:\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_NOEXIST\n\n\n\n\n\nExample: Multiple Flash Area Assignment Error Message\n\n\nThe following example shows the error message that newt outputs when multiple \nsettings are assigned the same flash area:\n\n\nError: Flash errors detected:\n Multiple flash_owner settings specify the same flash area\n settings: REBOOT_LOG_FLASH_AREA, CONFIG_FCB_FLASH_AREA\n flash area: FLASH_AREA_NFFS\n\nSetting history (newest -\n oldest):\n CONFIG_FCB_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS, sys/config:]\n REBOOT_LOG_FLASH_AREA: [apps/slinky:FLASH_AREA_NFFS, sys/reboot:]\n\n\n\n\n\nThe above error occurs because the \nhw/bsp/native\n package assigns \nthe \nFLASH_AREA_NFFS\n flash area to the \nsys/config/\n package \n\nCONFIG_FCB_FLASH_AREA\n setting, and the \napps/slinky\n package \nalso assigns \nFLASH_AREA_NFFS\n to the \nsys/reboot\n package \n\nREBOOT_LOG_FLASH_AREA\n setting. The following are excerpts of the \ntwo definitions and the two overrides from the \nsyscfg.yml\n files \nthat cause the error:\n\n\n# Package: sys/config\nsyscfg.defs.CONFIG_FCB:\n CONFIG_FCB_FLASH_AREA:\n description: \nThe flash area for the Config Flash Circular Buffer\n\n type: \nflash_owner\n\n value:\n\n# Package: sys/reboot\nsyscfg.defs:\n REBOOT_LOG_FLASH_AREA:\n description: \nThe flash area for the reboot log\n\n type: \nflash_owner\n \n value:\n\n#Package: hw/bsp/native\nsyscfg.vals:\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n\n#Package: apps/slinky\nsyscfg.vals: \n REBOOT_LOG_FLASH_AREA: FLASH_AREA_NFFS\n\n\n\n\n\n\n\nRestriction Violations\n\n\nFor setting definitions with \nrestrictions\n specified, newt checks for \nthe following violations:\n\n\n\n\nA setting with a \n$notnull\n restriction does not have a value. \n\n\nFor a setting with expression restrictions, some required setting \nvalues in the expressions evaluate to false. \n\n\n\n\nExample: $notnull Restriction Violation Error Messa ge\n\n\nThe following example shows the error message that newt outputs when\na setting with \n$notnull\n restriction does not have a value:\n\n\nError: Syscfg restriction violations detected:\n NFFS_FLASH_AREA must not be null \n\nSetting history (newest -\n oldest):\n NFFS_FLASH_AREA: [fs/nffs:]\n\n\n\n\n\nThe above error occurs because the \nfs/nffs\n package defines the \nNFFS_FLASH_AREA\n \nsetting with a \n$notnull\n restriction and no packages override the setting. The \nfollowing is an excerpt of the definition in the \nsyscfg.yml\n file that causes the error:\n\n\n#Package: fs/nffs\nsyscfg.defs:\n NFFS_FLASH_AREA:\n description: \nThe flash area to use for the Newtron Flash File System\n\n type: flash_owner\n value:\n restrictions:\n - $notnull\n\n\n\n\n\nExample: Expression Restriction Violation Error Message\n\n\nThe following example shows the error message that newt outputs for \nan expression restriction violation:\n\n\n Error: Syscfg restriction violations detected:\n CONFIG_FCB=1 requires CONFIG_FCB_FLASH_AREA be set, but CONFIG_FCB_FLASH_AREA=\n\nSetting history (newest -\n oldest):\n CONFIG_FCB: [targets/sim_slinky:1, sys/config:0]\n CONFIG_FCB_FLASH_AREA: [sys/config:]\n\n\n\n\n\nThe above error occurs because the \nsys/config\n package defines the \nCONFIG_FCB\n setting with \na restriction that when set, requires that the \nCONFIG_FCB_FLASH_AREA\n setting must \nalso be set. The following are excerpts of the definition and the override from the \nsyscfg.yml\n \nfiles that cause the error:\n\n\n# Package: sys/config\nsyscfg.defs:\n CONFIG_FCB:\n description: \nUses Config Flash Circular Buffer\n\n value: 0\n restrictions:\n - \n!CONFIG_NFFS\n\n - \nCONFIG_FCB_FLASH_AREA\n\n\n# Package: targets/sim_slinky\nsyscfg.vals:\n CONFIG_FCB: 1\n\n\n\n\n\n\n\nTask Priority Violations\n\n\nFor \ntask_priority\n type setting definitions, newt chec ks for the following violations:\n\n\n\n\nA task priority number is assigned to multiple settings. \n\n\nThe task priority number is greater than 239.\n\n\n\n\nExample: Duplicate Task Priority Assignment Error Message\n\n\nThe following example shows the error message that newt outputs when\na task priority number is assigned to multiple settings.\n\n\nNote:\n The settings used in this example are not actual \napps/slinky\n and \nsys/shell\n settings.\nThese settings are created for this example because currently only one Mynewt package \ndefines a \ntask_priority\n type setting. \n\n\nError: duplicate priority value: setting1=SHELL_TASK_PRIORITY setting2=SLINKY_TASK_PRIORITY pkg1=apps/slinky pkg2=sys/shell value=1\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n package defines a \nSLINKY_TASK_PRIORITY\n \nsetting with a default task priority of 1 and the \nsys/shell\n package also defines a \n\nSHELL_TASK_PRIORITY\n setting with a default task priority of 1.\n\n\nExa mple: Invalid Task Priority Error Message\n\n\nThe following example shows the error message that newt outputs when\na setting is assigned an invalid task priority value:\n\n\nError: invalid priority value: value too great (\n 239); setting=SLINKY_TASK_PRIORITY value=240 pkg=apps/slinky\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n package defines the \nSLINKY_TASK_PRIORITY\n setting \nwith 240 for the default task priority value. \n\n\nNote:\n Newt does not output the \nSetting history\n with task priority violation error messages. \n\n\n\n\nDuplicate System Configuration Setting Definition\n\n\nA setting definition must be unique. Newt checks that only one package in the \ntarget defines a setting. The following example shows the error message that newt \noutputs when multiple packages define the \nLOG_NEWTMGR\n setting:\n\n\nError: setting LOG_NEWTMGR redefined\n\n\n\n\n\nNote:\n Newt does not output the \nSetting history\n with duplicate setting error messages. ", + "text": "Validation and Error Messages\n\n\nWith multiple packages defining and overriding system configuration settings, it \nis easy to introduce conflicts and violations that are difficult to find. The \n\nnewt build \ntarget-name\n command validates the setting definitions and value \noverrides for all the packages in the target to ensure a valid and consistent build.\nIt aborts the build when it detects violations or ambiguities between packages.\n\nThe following sections describe the error conditions that newt detects and \nthe error messages that it outputs. For most errors, newt also outputs \nthe \nSetting history\n with the order of package overrides to help \nyou resolve the errors.\n\n\nNote:\n The \nnewt target config \ntarget-name\n command also detects \nerrors and outputs error messages at the top of the command output. \nThe command outputs the package setting definitions and values after it \noutputs the error messages. It is easy to miss the error mes sages at the top. \n\n\nValue Override Violations\n\n\nThe newt tool uses package priorities to resolve override conflicts. It uses \nthe value override from the highest priority package when multiple \npackages override the same setting. Newt checks for the following \noverride violations:\n\n\n\n\nAmbiguity Violation - Two packages of the same priority override a setting with \ndifferent values. And no higher priority package overrides the setting.\n\n\nPriority Violation - A package overrides a setting defined by a package with higher or \nequal priority. \n\n\n\n\nExample: Ambiguity Violation Error Message\n\n\nThe following example shows the error message that newt outputs for an ambiguity violation:\n\n\nError: Syscfg ambiguities detected:\n Setting: LOG_NEWTMGR, Packages: [apps/slinky, apps/splitty]\nSetting history (newest -\n oldest):\n LOG_NEWTMGR: [apps/splitty:0, apps/slinky:1, sys/log/full:0]\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n and \napps /splitty\n packages \nin the split image target both override the same setting with different \nvalues. The \napps/slinky\n package sets the \nsys/log/full\n package \nLOG_NEWTMGR\n \nsetting to 1, and the \napps/splitty\n package sets the setting to 0. The \noverrides are ambiguous because both are \napp\n packages and \nhave the same priority. The following are excerpts of the defintion \nand the two overrides from the \nsyscfg.yml\n files that cause the error:\n\n\n#Package: sys/log/full\nsyscfg.defs:\n LOG_NEWTMGR:\n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n#Package: apps/slinky\nsyscfg.vals:\n LOG_NEWTMGR: 1\n\n#Package: apps/splitty\nsyscfg.vals:\n LOG_NEWTMGR: 0\n\n\n\n\n\nExample: Priority Violation Error Message\n\n\nThe following example shows the error message that newt outputs for a priority violation \nwhere a package tries to change the setting that was defined by another package at \nthe same priority lev el:\n\n\nError: Priority violations detected (Packages can only override settings defined by packages of lower priority):\n Package: mgmt/newtmgr overriding setting: LOG_NEWTMGR defined by sys/log/full\n\nSetting history (newest -\n oldest):\n LOG_NEWTMGR: [sys/log/full:0]\n\n\n\n\n\nThe above error occurs because the \nmgmt/newtmgr\n lib package \noverrides the \nLOG_NEWTMGR\n setting that the \nsys/log/full\n lib package \ndefines. The following are excerpts of the definition and the override from the \n\nsyscfg.yml\n files that cause this error: \n\n\n#Package: sys/log/full\nsyscfg.defs:\n LOG_NEWTMGR:\n description: \nEnables or disables newtmgr command tool logging\n\n value: 0\n\n#Package: mgmt/newtmgr\nsyscfg.vals:\n LOG_NEWTMGR: 1\n\n\n\n\n\n\n\nFlash Area Violations\n\n\nFor \nflash_owner\n type setting definitions, newt checks \nfor the following violations:\n\n\n\n\nAn undefined flash area is assigned to a setting.\n\n\nA flash area is assigned to multiple settings.\n\n\n\n\nExample: Undefined Flash Area Error Message\n\n\nThe following example shows the error message that newt outputs for an undefined flash area.\n\n\nBuilding target targets/sim_slinky\nError: Flash errors detected:\n Setting REBOOT_LOG_FLASH_AREA specifies unknown flash area: FLASH_AREA_NOEXIST\n\nSetting history (newest -\n oldest):\n REBOOT_LOG_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NOEXIST, sys/reboot:]\n\n\n\n\n\nThe above error occurs because the \nhw/bsp/native\n package assigns the \nundefined \nFLASH_AREA_NOEXIST\n flash area to the \nsys/reboot\n package \n\nREBOOT_LOG_FLASH_AREA\n setting. The following are excerpts of the definition \nand the override from the \nsyscfg.yml\n files that cause the error:\n\n\n#Package: sys/reboot\nsyscfg.defs:\n REBOOT_LOG_FLASH_AREA:\n description: \nFlash Area to use for reboot log.\n\n type: flash_owner\n value:\n\n#Package: hw/bsp/native\nsyscfg.vals:\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_NOEXIST\n\n\n\n\n\nExample: Multiple Flash Area Assignment Error Message\n\n\nThe following example shows the error message that newt outputs when multiple \nsettings are assigned the same flash area:\n\n\nError: Flash errors detected:\n Multiple flash_owner settings specify the same flash area\n settings: REBOOT_LOG_FLASH_AREA, CONFIG_FCB_FLASH_AREA\n flash area: FLASH_AREA_NFFS\n\nSetting history (newest -\n oldest):\n CONFIG_FCB_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS, sys/config:]\n REBOOT_LOG_FLASH_AREA: [apps/slinky:FLASH_AREA_NFFS, sys/reboot:]\n\n\n\n\n\nThe above error occurs because the \nhw/bsp/native\n package assigns \nthe \nFLASH_AREA_NFFS\n flash area to the \nsys/config/\n package \n\nCONFIG_FCB_FLASH_AREA\n setting, and the \napps/slinky\n package \nalso assigns \nFLASH_AREA_NFFS\n to the \nsys/reboot\n package \n\nREBOOT_LOG_FLASH_AREA\n setting. The following are excerpts of the \ntwo definitions and the two overrides from the \nsyscfg.yml\n files \nthat cause the error:\n\n\n# Package: sys/config\nsyscfg.defs.CONFIG_FCB:\n CONFIG_FCB_FLASH_AREA:\n description: \nThe flash area for the Config Flash Circular Buffer\n\n type: \nflash_owner\n\n value:\n\n# Package: sys/reboot\nsyscfg.defs:\n REBOOT_LOG_FLASH_AREA:\n description: \nThe flash area for the reboot log\n\n type: \nflash_owner\n \n value:\n\n#Package: hw/bsp/native\nsyscfg.vals:\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n\n#Package: apps/slinky\nsyscfg.vals: \n REBOOT_LOG_FLASH_AREA: FLASH_AREA_NFFS\n\n\n\n\n\n\n\nRestriction Violations\n\n\nFor setting definitions with \nrestrictions\n specified, newt checks for \nthe following violations:\n\n\n\n\nA setting with a \n$notnull\n restriction does not have a value. \n\n\nFor a setting with expression restrictions, some required setting \nvalues in the expressions evaluate to false. \n\n\n\n\nExample: $notnull Restriction Violation Error Messa ge\n\n\nThe following example shows the error message that newt outputs when\na setting with \n$notnull\n restriction does not have a value:\n\n\nError: Syscfg restriction violations detected:\n NFFS_FLASH_AREA must not be null \n\nSetting history (newest -\n oldest):\n NFFS_FLASH_AREA: [fs/nffs:]\n\n\n\n\n\nThe above error occurs because the \nfs/nffs\n package defines the \nNFFS_FLASH_AREA\n \nsetting with a \n$notnull\n restriction and no packages override the setting. The \nfollowing is an excerpt of the definition in the \nsyscfg.yml\n file that causes the error:\n\n\n#Package: fs/nffs\nsyscfg.defs:\n NFFS_FLASH_AREA:\n description: \nThe flash area to use for the Newtron Flash File System\n\n type: flash_owner\n value:\n restrictions:\n - $notnull\n\n\n\n\n\nExample: Expression Restriction Violation Error Message\n\n\nThe following example shows the error message that newt outputs for \nan expression restriction violation:\n\n\n Error: Syscfg restriction violations detected:\n CONFIG_FCB=1 requires CONFIG_FCB_FLASH_AREA be set, but CONFIG_FCB_FLASH_AREA=\n\nSetting history (newest -\n oldest):\n CONFIG_FCB: [targets/sim_slinky:1, sys/config:0]\n CONFIG_FCB_FLASH_AREA: [sys/config:]\n\n\n\n\n\nThe above error occurs because the \nsys/config\n package defines the \nCONFIG_FCB\n setting with \na restriction that when set, requires that the \nCONFIG_FCB_FLASH_AREA\n setting must \nalso be set. The following are excerpts of the definition and the override from the \nsyscfg.yml\n \nfiles that cause the error:\n\n\n# Package: sys/config\nsyscfg.defs:\n CONFIG_FCB:\n description: \nUses Config Flash Circular Buffer\n\n value: 0\n restrictions:\n - \n!CONFIG_NFFS\n\n - \nCONFIG_FCB_FLASH_AREA\n\n\n# Package: targets/sim_slinky\nsyscfg.vals:\n CONFIG_FCB: 1\n\n\n\n\n\n\n\nTask Priority Violations\n\n\nFor \ntask_priority\n type setting definitions, newt chec ks for the following violations:\n\n\n\n\nA task priority number is assigned to multiple settings. \n\n\nThe task priority number is greater than 239.\n\n\n\n\nExample: Duplicate Task Priority Assignment Error Message\n\n\nThe following example shows the error message that newt outputs when\na task priority number is assigned to multiple settings.\n\n\nNote:\n The settings used in this example are not actual \napps/slinky\n and \nsys/shell\n settings.\nThese settings are created for this example because currently only one Mynewt package \ndefines a \ntask_priority\n type setting. \n\n\nError: duplicate priority value: setting1=SHELL_TASK_PRIORITY setting2=SLINKY_TASK_PRIORITY pkg1=apps/slinky pkg2=sys/shell value=1\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n package defines a \nSLINKY_TASK_PRIORITY\n \nsetting with a default task priority of 1 and the \nsys/shell\n package also defines a \n\nSHELL_TASK_PRIORITY\n setting with a default task priority of 1.\n\n\nExa mple: Invalid Task Priority Error Message\n\n\nThe following example shows the error message that newt outputs when\na setting is assigned an invalid task priority value:\n\n\nError: invalid priority value: value too great (\n 239); setting=SLINKY_TASK_PRIORITY value=240 pkg=apps/slinky\n\n\n\n\n\nThe above error occurs because the \napps/slinky\n package defines the \nSLINKY_TASK_PRIORITY\n setting \nwith 240 for the default task priority value. \n\n\nNote:\n Newt does not output the \nSetting history\n with task priority violation error messages. \n\n\n\n\nDuplicate System Configuration Setting Definition\n\n\nA setting definition must be unique. Newt checks that only one package in the \ntarget defines a setting. The following example shows the error message that newt \noutputs when multiple packages define the \nLOG_NEWTMGR\n setting:\n\n\nError: setting LOG_NEWTMGR redefined\n\n\n\n\n\nNote:\n Newt does not output the \nSetting history\n with duplicate setting error messages. \n\n\n\nOverride of Undefined System Configuration Setting\n\n\nThe \nnewt build\n command ignores overrides of undefined system configuration settings. The command does not print a warning when you run it with the default log level. If you override a setting and the value is not assigned to the setting, you may have misspelled the setting name or a package no longer defines the setting. You have two options to troubleshoot this problem:\n\n\n\n\nRun the \nnewt target config show\n command to see the configuration setting definitions and overrides.\n\n\nRun the \nnewt build -ldebug\n command to build your target with DEBUG log level. \n\n\n\n\nNote: The \nnewt build -ldebug\n command generates lots of output and we recommend that you use the \nnewt target config show\n command option.\n\n\n\nExample: Ignoring Override of Undefined Setting Message\n\n\nThe following example shows that the \napps/slinky\n application overrides the \nLOG_NEWTMGR\n setting but omits the \nT\n as an e xample of an error and overrides the misspelled \nLOG_NEWMGR\n setting. Here is an excerpt from its \nsyscfg.yml\n file: \n\n\n#package: apps/slinky\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n ...\n\n # Enable newtmgr commands.\n STATS_NEWTMGR: 1\n LOG_NEWMGR: 1\n\n\n\n\n\n\nThe \nnewt target config show slinky_sim\n command outputs the following WARNING message:\n\n\n2017/02/18 17:19:12.119 [WARNING] Ignoring override of undefined settings:\n2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR\n2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA\n2017/02/18 17:19:12.119 [WARNING] Setting history (newest -\n oldest):\n2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR: [apps/slinky:1]\n2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS]\n\n\n\n\n\n\n\nThe \nnewt build -ldebug slinky_sim\n command outputs the following DEBUG message: \n\n\n2017/02/18 17:06:21.451 [DEBUG] Ignoring override of undefined settings:\n2 017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR\n2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA\n2017/02/18 17:06:21.451 [DEBUG] Setting history (newest -\n oldest):\n2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR: [apps/slinky:1]\n2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS]\n\n\n\n\n\n\n\nBSP Package Overrides Undefined Configuration Settings\n\n\nYou might see a warning that indicates your application's BSP package is overriding some undefined settings. As you can see from the previous example, the WARNING message shows that the \nhw/bsp/native\n package is overriding the undefined \nNFFS_FLASH_AREA\n setting. This is not an error because of the way a BSP package defines and assigns its flash areas to packages that use flash memory.\n\n\nA BSP package defines, in its \nbsp.yml\n file, a flash area map of the flash areas on the board. A package that uses flash memory must define a flash area configuration setting name. The BSP package ove rrides the package's flash area setting with one of the flash areas from its flash area map. A BSP package overrides the flash area settings for all packages that use flash memory because it does not know the packages that an application uses. When an application does not include one of these packages, the flash area setting for the package is undefined. You will see a message that indicates the BSP package overrides this undefined setting.\n\n\nHere are excerpts from the \nhw/bsp/native\n package's \nbsp.yml\n and \nsyscfg.yml\n files for the \nslinky_sim\n target. The BSP package defines the flash area map in its \nbsp.yml\n file and overrides the flash area settings for all packages in its \nsyscfg.yml\n file. The \nslinky_sim\n target does not use the \nfs/nffs\n package which defines the \nNFFS_FLASH_AREA\n setting. Newt warns that the \nhw/bsp/native\n packages overrides the undefined \nNFFS_FLASH_AREA\n setting.\n\n\n# hw/bsp/native bsp.yml\nbsp.flash_map:\n areas:\n # System areas.\n FLASH_AREA_BOOTLOADER:\n device: 0\n offset: 0x00000000\n size: 16kB\n\n ...\n\n FLASH_AREA_IMAGE_SCRATCH:\n device: 0\n offset: 0x000e0000\n size: 128kB\n\n # User areas.\n FLASH_AREA_REBOOT_LOG:\n user_id: 0\n device: 0\n offset: 0x00004000\n size: 16kB\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x00008000\n\n# hw/bsp/native syscfg.yml\nsyscfg.vals:\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG", "title": "Validation and Error Messages" }, { @@ -8011,6 +8011,21 @@ "title": "Duplicate System Configuration Setting Definition" }, { + "location": "/os/modules/sysinitconfig/sysconfig_error/#override-of-undefined-system-configuration-setting", + "text": "The newt build command ignores overrides of undefined system configuration settings. The command does not print a warning when you run it with the default log level. If you override a setting and the value is not assigned to the setting, you may have misspelled the setting name or a package no longer defines the setting. You have two options to troubleshoot this problem: Run the newt target config show command to see the configuration setting definitions and overrides. Run the newt build -ldebug command to build your target with DEBUG log level. Note: The newt build -ldebug command generates lots of output and we recommend that you use the newt target config show command option.", + "title": "Override of Undefined System Configuration Setting" + }, + { + "location": "/os/modules/sysinitconfig/sysconfig_error/#example-ignoring-override-of-undefined-setting-message", + "text": "The following example shows that the apps/slinky application overrides the LOG_NEWTMGR setting but omits the T as an example of an error and overrides the misspelled LOG_NEWMGR setting. Here is an excerpt from its syscfg.yml file: #package: apps/slinky\nsyscfg.vals:\n # Enable the shell task.\n SHELL_TASK: 1\n ...\n\n # Enable newtmgr commands.\n STATS_NEWTMGR: 1\n LOG_NEWMGR: 1 \nThe newt target config show slinky_sim command outputs the following WARNING message: 2017/02/18 17:19:12.119 [WARNING] Ignoring override of undefined settings:\n2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR\n2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA\n2017/02/18 17:19:12.119 [WARNING] Setting history (newest - oldest):\n2017/02/18 17:19:12.119 [WARNING] LOG_NEWMGR: [apps/slinky:1]\n2017/02/18 17:19:12.119 [WARNING] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS] The newt build -ldebug slinky_sim command outputs the fo llowing DEBUG message: 2017/02/18 17:06:21.451 [DEBUG] Ignoring override of undefined settings:\n2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR\n2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA\n2017/02/18 17:06:21.451 [DEBUG] Setting history (newest - oldest):\n2017/02/18 17:06:21.451 [DEBUG] LOG_NEWMGR: [apps/slinky:1]\n2017/02/18 17:06:21.451 [DEBUG] NFFS_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS]", + "title": "Example: Ignoring Override of Undefined Setting Message" + }, + { + "location": "/os/modules/sysinitconfig/sysconfig_error/#bsp-package-overrides-undefined-configuration-settings", + "text": "You might see a warning that indicates your application's BSP package is overriding some undefined settings. As you can see from the previous example, the WARNING message shows that the hw/bsp/native package is overriding the undefined NFFS_FLASH_AREA setting. This is not an error because of the way a BSP package defines and assigns its flash areas to packages that use flash memory. A BSP package defines, in its bsp.yml file, a flash area map of the flash areas on the board. A package that uses flash memory must define a flash area configuration setting name. The BSP package overrides the package's flash area setting with one of the flash areas from its flash area map. A BSP package overrides the flash area settings for all packages that use flash memory because it does not know the packages that an application uses. When an application does not include one of these packages, the flash area setting for the package is undefined. You will see a message t hat indicates the BSP package overrides this undefined setting. Here are excerpts from the hw/bsp/native package's bsp.yml and syscfg.yml files for the slinky_sim target. The BSP package defines the flash area map in its bsp.yml file and overrides the flash area settings for all packages in its syscfg.yml file. The slinky_sim target does not use the fs/nffs package which defines the NFFS_FLASH_AREA setting. Newt warns that the hw/bsp/native packages overrides the undefined NFFS_FLASH_AREA setting. # hw/bsp/native bsp.yml\nbsp.flash_map:\n areas:\n # System areas.\n FLASH_AREA_BOOTLOADER:\n device: 0\n offset: 0x00000000\n size: 16kB\n\n ...\n\n FLASH_AREA_IMAGE_SCRATCH:\n device: 0\n offset: 0x000e0000\n size: 128kB\n\n # User areas.\n FLASH_AREA_REBOOT_LOG:\n user_id: 0\n device: 0\n offset: 0x00004000\n size: 16kB\n FLASH_AREA_NFFS:\n user_id: 1\n device: 0\n offset: 0x00008000\n\n# hw/bsp/native syscfg.yml\nsyscfg.vals:\n NFFS_FLASH_AREA: FLASH_AREA_NFFS\n CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS\n REBOOT_LOG_FLASH_AREA: FLASH_AREA_REBOOT_LOG", + "title": "BSP Package Overrides Undefined Configuration Settings" + }, + { "location": "/network/ble/ble_intro/", "text": "BLE Introduction\n\n\nApache Mynewt offers the world's first fully open-source Bluetooth Low Energy (BLE) or Bluetooth Smart stack fully compliant with BLE 4.2 specifications. It is called NimBLE. \n\n\nBLE technology operates in the unlicensed industrial, scientific and medical (ISM) band at 2.4 to 2.485 GHz which is available in most countries. It uses a spread spectrum, frequency hopping, full-duplex signal. BLE FHSS employs 40 2-MHz-wide channels to ensure greater reliability over longer distances. It also features 0-dBm (1 mW) power output and a typical maximum range of 50 meters. Note that BLE is not compatible with standard Bluetooth.\n\n\n\n\nFeature Support\n\n\nNimBLE complies with Bluetooth Core Specification 4.2 which introduces several new features that make it an ideal wireless technology for the Internet of Things (IoT).\n\n\n\n\nLE Privacy 1.2 for frequent changes to the device address to make it difficult to track for outsiders\n\n\nLE Secure Co nnections featuring FIPS-compliant algorithms.\n\n\nLE Data Length Extension for higher throughput\n\n\nComing Soon\n: Assigning an Internet Protocol (IP) address (complaint with the IPv6 or 6LoWPAN standard) to a Bluetooth device through Internet Protocol Support Profile (IPSP)\n\n\n\n\nComponents\n\n\nA Bluetooth low energy stack (NimBLE included) consists of two components with several subcomponents:\n\n\n\n\n\n\nController\n\n\n\n\nPhysical Layer\n: adaptive frequency-hopping Gaussian Frequency Shift Keying (GFSK) radio using 40 RF channels (0-39), with 2 MHz spacing.\n\n\nLink Layer\n: with one of five states (Standby, Advertising, Scanning, Initiating, Connection states) active at any time\n\n\n\n\n\n\n\n\nHost\n\n\n\n\nLogical Link Control and Adaptation Protocol (L2CAP)\n: provides logical channels, named L2CAP channels, which are multiplexed over one or more logical links to provide packet segmentation and reassembly, flow control, error control, streaming, QoS etc. \n\n\nS ecurity Manager (SM)\n: uses Security Manager Protocol (SMP) for pairing and transport specific key distribution for securing radio communication \n\n\nAttribute protocol (ATT)\n: allows a device (\nServer\n) to expose certain pieces of data, known as \nAttributes\n, to another device (\nClient\n)\n\n\nGeneric Attribute Profile (GATT)\n: a framework for using the ATT protocol to exchange attributes encapsulated as \nCharacteristics\n or \nServices\n \n\n\nGeneric Access Profile (GAP)\n: a base profile which all Bluetooth devices implement, which in the case of LE, defines the Physical Layer, Link Layer, L2CAP, Security Manager, Attribute Protocol and Generic Attribute Profile. \n\n\nHost Controller Interface (HCI)\n: the interface between the host and controller either through software API or by a hardware interface such as SPI, UART or USB.\n\n\n\n\n\n\n\n\nSubsequent chapters in this manual will go into the details of the implementation of each component, APIs available, and thing s to consider while designing a NimBLE app.\n\n\n\n\nExample NimBLE projects\n\n\nMynewt comes with several built-in projects or applications using NimBLE. These allow users to try out NimBLE, understand how to use available services, and build their own applications using one or more of the examples as seed.\n\n\n\n\n\n\nbletiny\n : A simple shell application which provides a basic interface to the host-side of the BLE stack. Supported operations include GAP, GATT, and L2CAP.\n\n\n\n\n\n\nbleprph\n: A basic peripheral device with no user interface. It advertises automatically on startup, and resumes advertising whenever a connection is terminated. It supports a maximum of one connection.\n\n\n\n\n\n\nblecent\n: A basic central device with no user interface. This application scans for a peripheral that supports the alert notification service (ANS). Upon discovering such a peripheral, blecent connects and performs the following actions:\n\n\n\n\nReads the ANS Supported New Alert Ca tegory characteristic.\n\n\nWrites the ANS Alert Notification Control Point characteristic.\n\n\nSubscribes to notifications for the ANS Unread Alert Status characteristic.\n\n\n\n\n\n\n\n\nblehci\n: Implements a BLE controller-only application. A separate host-only implementation, such as Linux's BlueZ, can interface with this application via HCI over UART.\n\n\n\n\n\n\nbleuart\n: Implements a simple BLE peripheral that supports the Nordic\n\nUART / Serial Port Emulation service", "title": "NimBLE Introduction" @@ -10182,7 +10197,7 @@ }, { "location": "/newt/newt_intro/", - "text": "Newt Tool\n\n\nIntroduction\n\n\nNewt is a smart build and package management system for embedded contexts. It is a single tool that accomplishes both the following goals:\n\n\n\n\nsource package management \n\n\nbuild, debug and install.\n\n\n\n\nRationale\n\n\nIn order for the Mynewt operating system to work well for constrained environments across the many different types of microcontroller applications (from doorbells to medical devices to power grids), a system is needed that lets you select which packages to install and which packages to build.\n\n\nThe build systems for embedded devices are often fairly complicated and not well served for this purpose. For example, autoconf is designed for detecting system compatibility issues but not well suited when it comes to tasks like:\n\n\n\n\nBuilding for multiple targets\n\n\nDeciding what to build in and what not to build in\n\n\nManaging dependencies between components\n\n\n\n\nFortunately, solutions addressi ng these very issues can be found in source package management systems in higher level languages such as Javascript \n(Node), Go, PHP and Ruby. We decided to fuse their source management \nsystems with a make system built for embedded systems and create Newt.\n\n\nBuild System\n\n\nA good build system must allow the user to take a few common steps while developing embedded applications:\n\n\n\n\nGenerate full flash images\n\n\nDownload debug images to a target board using a debugger\n\n\nConditionally compile libraries \n code based upon build settings\n\n\n\n\nNewt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop:\n\n\n$ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\n\u251c\u2500\u2500 apps\n\n\u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u25 00\u2500 src\n\u251c\u2500\u2500 project.yml\n\n\u2514\u2500\u2500 targets\n\n \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files\n\n\n\n\n\n\n\nWhen Newt sees a directory tree that contains a \"project.yml\" file, it is smart enough to recognize it as the base directory of a project, and \nautomatically builds a package tree. It also recognizes two important package directories in the package tree - \"apps\" and \"targets\". More on these directories in \nNewt Theory of Ops\n.\n\n\nWhen Newt is told to build a project, it recursively resolves all package dependencies and generates artifacts that are placed in the bin/ directory at the top-level of the project. The artifact directory is prefixed by the target name being built - \nmy_blinky_sim\n for example:\n\n\n$ tree bin\n bin\n\u2514\u2500\u2500 my_blinky_sim\n \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.a\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.a.cmd\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.cmd\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 Contents\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 Info.plist\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 Resources\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 DWARF\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.lst\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.d\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.o\n \ u2502\u00a0\u00a0 \u2514\u2500\u2500 main.o.cmd\n \u251c\u2500\u2500 hw\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 native\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal_bsp.d\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal_bsp.o\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal_bsp.o.cmd\n\nsnip\n\n\n\n\n\n\n\n\nMore operations using Newt\n\n\nOnce a target has been built, Newt allows additional operations on the target. \n\n\n\n\nload\n: Download built target to board\n\n\ndebug\n: Open debugger session to target\n\n\nsize\n: Get size of target components\n\n\ncreate-image\n: Add image header to the binary image\n\n\nrun\n: Build, create image, load, and finally open a debug session with the target\n\n\n\n\nFor more details on how Newt works, go to \nNewt - Theory of Operations\n.\n\n\n\n\nSource Management and Repositories\n\n\nThe other major element of the Newt tool is the ability to create reusable source distributions from a collection of code. \nA project can be a reusable container of source code.\n In other words, projects can be versioned and redistributed, not packages. A project bundles together packages that are typically needed to work together in a product e.g. RTOS core, filesystem APIs, and networking stack.\n\n\nA project that has been made redistributable is known as a \nrepository\n. \nRepositories can be added to your local project by adding them into your project.yml file. Here is an example of the blinky project's yml file which relies on apache-mynewt-core:\n\n\n$ more project.yml\n\nsnip\n\nproject.repositories:\n - apache-mynewt-core\n\n# Use github\ns distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 0-latest\n user: apache\n repo: incubator-mynewt-core\n\n\n\n\n\n\n\nWhen y ou specify this repository in the blinky's project file, you can then use the Newt tool to install dependencies:\n\n\n$ newt install\nDownloading repository description for apache-mynewt-core... success!\nDownloading repository incubator-mynewt-core (branch: develop) at \nhttps://github.com/apache/incubator-mynewt-core.git\nCloning into \n\n/var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459\n...\nremote: Counting objects: 17601, done.\nremote: Compressing objects: 100% (300/300), done.\nremote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284\nReceiving objects: 100% (17601/17601), 6.09 MiB | 3.17 MiB/s, done.\nResolving deltas: 100% (10347/10347), done.\nChecking connectivity... done.\nRepos successfully installed\n\n\n\n\n\n\n\nNewt will install this repository in the \n/repos directory. In the case of blinky, the directory structure ends up looking like:\n\n\n$ tree -L 2\n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2 500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502 \u2514\u2500\u2500 blinky\n\u251c\u2500\u2500 project.state\n\u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repos\n\u2502 \u2514\u2500\u2500 apache-mynewt-core\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2514\u2500\u2500 unittest\n\n\n\n\n\n\n\nIn order to reference the installed repositories in packages, the \"@\" notation should be specified in the repository specifier. As an example, the apps/blinky application has the following dependencies in its pkg.yml file. This tells the build system to look in the base directory of repos/apache-mynewt-core for the \nlibs/os\n, \nhw/hal\n, and \nlibs/console/full\n packages.\n\n\n$ more apps/blinky/pkg.yml\n\nsnip\n\npkg.deps:\n - \n@apache-mynewt-core/libs/os\n\n - \n@apache-mynewt-core/hw/hal\n\n - \n@apache-mynewt-core/libs/console/full\n\n\n\n\n\n\n\n\nAutocompletion in Bash\n\n\nNewt has the ability to autocompl ete within \nbash\n. The following instructions allow MAC users to enable autocomplete within \nbash\n.\n\n\n\n\nInstall the autocomplete tools for bash via \nbrew install bash-completion\n\n\nTell your shell to use newt for autocompletion of newt via \ncomplete -C \"newt complete\" newt\n. You can add this to your .bashrc or other init file to have it automatically set for all bash shells.\n\n\n\n\nNotes:\n\n\n\n\nAutocomplete will give you flag hints, but only if you type a '-'. \n\n\nAutocomplete will not give you completion hints for the flag arguments (those optional things after the flag like \n-l DEBUG\n)\n\n\nAutocomplete uses newt to parse the project to find targets and libs.", + "text": "Newt Tool\n\n\nIntroduction\n\n\nNewt is a smart build and package management system for embedded contexts. It is a single tool that accomplishes both the following goals:\n\n\n\n\nsource package management \n\n\nbuild, debug and install.\n\n\n\n\nRationale\n\n\nIn order for the Mynewt operating system to work well for constrained environments across the many different types of microcontroller applications (from doorbells to medical devices to power grids), a system is needed that lets you select which packages to install and which packages to build.\n\n\nThe build systems for embedded devices are often fairly complicated and not well served for this purpose. For example, autoconf is designed for detecting system compatibility issues but not well suited when it comes to tasks like:\n\n\n\n\nBuilding for multiple targets\n\n\nDeciding what to build in and what not to build in\n\n\nManaging dependencies between components\n\n\n\n\nFortunately, solutions addressi ng these very issues can be found in source package management systems in higher level languages such as Javascript \n(Node), Go, PHP and Ruby. We decided to fuse their source management \nsystems with a make system built for embedded systems and create Newt.\n\n\nBuild System\n\n\nA good build system must allow the user to take a few common steps while developing embedded applications:\n\n\n\n\nGenerate full flash images\n\n\nDownload debug images to a target board using a debugger\n\n\nConditionally compile libraries \n code based upon build settings\n\n\n\n\nNewt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop:\n\n\n$ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\n\u251c\u2500\u2500 apps\n\n\u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u25 00\u2500 src\n\u251c\u2500\u2500 project.yml\n\n\u2514\u2500\u2500 targets\n\n \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files\n\n\n\n\n\n\n\nWhen Newt sees a directory tree that contains a \"project.yml\" file, it is smart enough to recognize it as the base directory of a project, and \nautomatically builds a package tree. It also recognizes two important package directories in the package tree - \"apps\" and \"targets\". More on these directories in \nNewt Theory of Ops\n.\n\n\nWhen Newt builds a target, it recursively resolves all package dependencies, and generates artifacts that are placed in the bin/targets/\ntarget-name\n/app/apps/\napp-name\n directory, where the bin directory is under the project base directory, \ntarget-name\n is the name of the target, and \napp -name\n is the name of the application. For our example \nmy_blinky_sim\n is the name of the target and \nblinky\n is the name of the application. The \nblinky.elf\n executable is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the source tree:\n\n\ntree -L 6 bin/\nbin/\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 app\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u2502\u00a0\u00 a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.lst\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 manifest.json\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 native\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 drivers\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 uart\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 h w_hal.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_hal.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 repos\n\n\nsnip\n\n\n\n\n\n\n\n\nMore operations using Newt\n\n\nOnce a target has been built, Newt allows additional operations on the target. \n\n\n\n\nload\n: Download built target to board\n\n\ndebug\n: Open debugger session to target\n\n\nsize\n: Get size of target components\n\n\ncreate-image\n: Add image header to the binary image\n\n\nrun\n: Build, create image, load, and finally open a debug session with the target\n\n\ntarget\n: Create, delete, configure, and query a target\n\n\n\n\nFor more details on how Newt works, go to \nNewt - Theory of Operations\n.\n\n\n\n\nSource Management and Repositories\n\n\nThe other major element of the Newt tool is the ability to create reusable source distributions from a collection of code. \nA project can be a reusable container of source code.\n In other words, projects can be versioned and redistributed, not packages. A project bundles together packages that are typically needed to work together in a product e.g. RTOS core, filesystem APIs, and networking stack.\n\n\nA project that has been made redistributable is known as a \nrepository\n. \nRepositories can be added to your local project by adding them into your project.yml file. Here is an example of the blinky project's yml file which relies on apache-mynewt-core:\n\n\n$ more project.yml\n\nsnip\n\nproject.repositories:\n - apache-mynewt-core\n\n# Use github\ns distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 0-latest\n user: apache\n repo: incubator-mynewt-core\n\n\n\n\n\n\n\nWhen you specify this repository in the blinky's project file, you can then use the Newt tool to install dependencies:\n\n\n$ newt install\nDow nloading repository description for apache-mynewt-core... success!\nDownloading repository incubator-mynewt-core (branch: develop) at \nhttps://github.com/apache/incubator-mynewt-core.git\nCloning into \n\n/var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459\n...\nremote: Counting objects: 17601, done.\nremote: Compressing objects: 100% (300/300), done.\nremote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284\nReceiving objects: 100% (17601/17601), 6.09 MiB | 3.17 MiB/s, done.\nResolving deltas: 100% (10347/10347), done.\nChecking connectivity... done.\nRepos successfully installed\n\n\n\n\n\n\n\nNewt will install this repository in the \n/repos directory. In the case of blinky, the directory structure ends up looking like:\n\n\n$ tree -L 2\n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502 \u2514\u2500\u2500 blinky\n\u251c\u2500\u2500 project.state\n \u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repos\n\u2502 \u2514\u2500\u2500 apache-mynewt-core\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2514\u2500\u2500 unittest\n\n\n\n\n\n\n\nIn order to reference the installed repositories in packages, the \"@\" notation should be specified in the repository specifier. As an example, the apps/blinky application has the following dependencies in its pkg.yml file. This tells the build system to look in the base directory of repos/apache-mynewt-core for the \nkernel/os\n, \nhw/hal\n, and \nsys/console/full\n packages.\n\n\n$ more apps/blinky/pkg.yml\n\nsnip\n\npkg.deps:\n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/hw/hal\n\n - \n@apache-mynewt-core/sys/console/full\n\n\n\n\n\n\n\n\nAutocompletion in Bash\n\n\nNewt has the ability to autocomplete within \nbash\n. The following instructions allow MAC users to enable autocomplete within \nbash\n.\n\n\n\n\nInstall the autocompl ete tools for bash via \nbrew install bash-completion\n\n\nTell your shell to use newt for autocompletion of newt via \ncomplete -C \"newt complete\" newt\n. You can add this to your .bashrc or other init file to have it automatically set for all bash shells.\n\n\n\n\nNotes:\n\n\n\n\nAutocomplete will give you flag hints, but only if you type a '-'. \n\n\nAutocomplete will not give you completion hints for the flag arguments (those optional things after the flag like \n-l DEBUG\n)\n\n\nAutocomplete uses newt to parse the project to find targets and libs.", "title": "toc" }, { @@ -10202,17 +10217,17 @@ }, { "location": "/newt/newt_intro/#build-system", - "text": "A good build system must allow the user to take a few common steps while developing embedded applications: Generate full flash images Download debug images to a target board using a debugger Conditionally compile libraries code based upon build settings Newt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop: $ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md \u251c\u2500\u2500 apps \u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u2500\u2500 src\n\u251c\u2500\u2500 project.yml \u2514\u2500\u2500 targets \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files When Newt sees a directory tree that contains a \"project.yml\" file, it is smart enough to recognize it as the base directory of a project, and \nautomatically builds a package tree. It also recognizes two important package directories in the package tree - \"apps\" and \"targets\". More on these directories in Newt Theory of Ops . When Newt is told to build a project, it recursively resolves all package dependencies and generates artifacts that are placed in the bin/ directory at the top-level of the project. The artifact directory is prefixed by the target name being built - my_blinky_sim for example: $ tree bin\nbin\n\u2514\u2500\u2500 my_blinky_sim\n \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.a\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.a.cmd\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u251c\u 2500\u2500 blinky.elf.cmd\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 Contents\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 Info.plist\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 Resources\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 DWARF\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.lst\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.d\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 main.o\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 main.o.cmd\n \u251c\u2500\u2500 hw\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 native\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal_bsp.d\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2 500\u2500 hal_bsp.o\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal_bsp.o.cmd snip", + "text": "A good build system must allow the user to take a few common steps while developing embedded applications: Generate full flash images Download debug images to a target board using a debugger Conditionally compile libraries code based upon build settings Newt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop: $ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md \u251c\u2500\u2500 apps \u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u2500\u2500 src\n\u251c\u2500\u2500 project.yml \u2514\u2500\u2500 targets \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files When Newt sees a directory tree that contains a \"project.yml\" file, it is smart enough to recognize it as the base directory of a project, and \nautomatically builds a package tree. It also recognizes two important package directories in the package tree - \"apps\" and \"targets\". More on these directories in Newt Theory of Ops . When Newt builds a target, it recursively resolves all package dependencies, and generates artifacts that are placed in the bin/targets/ target-name /app/apps/ app-name directory, where the bin directory is under the project base directory, target-name is the name of the target, and app-name is the name of the application. For our example my_blinky_sim is the name of the target and blinky is the name of the application. The blinky.elf executable is stored in the bin/targets/my_blinky_sim/app/apps/blinky directory as shown in the source tree: tree -L 6 bin/\nbin/\n\u2514\u2500\u2500 targets\n \u251 c\u2500\u2500 my_blinky_sim\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 app\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 blinky\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 apps_blinky.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 blinky.elf.lst\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500 \u2500 manifest.json\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 bsp\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 native\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 drivers\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 uart\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hal\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_hal.a\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 hw_hal.a.cmd\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 repos snip", "title": "Build System" }, { "location": "/newt/newt_intro/#more-operations-using-newt", - "text": "Once a target has been built, Newt allows additional operations on the target. load : Download built target to board debug : Open debugger session to target size : Get size of target components create-image : Add image header to the binary image run : Build, create image, load, and finally open a debug session with the target For more details on how Newt works, go to Newt - Theory of Operations .", + "text": "Once a target has been built, Newt allows additional operations on the target. load : Download built target to board debug : Open debugger session to target size : Get size of target components create-image : Add image header to the binary image run : Build, create image, load, and finally open a debug session with the target target : Create, delete, configure, and query a target For more details on how Newt works, go to Newt - Theory of Operations .", "title": "More operations using Newt" }, { "location": "/newt/newt_intro/#source-management-and-repositories", - "text": "The other major element of the Newt tool is the ability to create reusable source distributions from a collection of code. A project can be a reusable container of source code. In other words, projects can be versioned and redistributed, not packages. A project bundles together packages that are typically needed to work together in a product e.g. RTOS core, filesystem APIs, and networking stack. A project that has been made redistributable is known as a repository . \nRepositories can be added to your local project by adding them into your project.yml file. Here is an example of the blinky project's yml file which relies on apache-mynewt-core: $ more project.yml snip \nproject.repositories:\n - apache-mynewt-core\n\n# Use github s distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 0-latest\n user: apache\n repo: incubator-mynewt-core When you specify this repository in the blinky's project file, you can then use the Newt tool to install dependencies: $ newt install\nDownloading repository description for apache-mynewt-core... success!\nDownloading repository incubator-mynewt-core (branch: develop) at \nhttps://github.com/apache/incubator-mynewt-core.git\nCloning into /var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459 ...\nremote: Counting objects: 17601, done.\nremote: Compressing objects: 100% (300/300), done.\nremote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284\nReceiving objects: 100% (17601/17601), 6.09 MiB | 3.17 MiB/s, done.\nResolving deltas: 100% (10347/10347), done.\nChecking connectivity... done.\nRepos successfully installed Newt will install this repository in the /repos directory. In the case of blinky, the directory structure ends up looking like: $ tree -L 2\n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\ u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502 \u2514\u2500\u2500 blinky\n\u251c\u2500\u2500 project.state\n\u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repos\n\u2502 \u2514\u2500\u2500 apache-mynewt-core\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2514\u2500\u2500 unittest In order to reference the installed repositories in packages, the \"@\" notation should be specified in the repository specifier. As an example, the apps/blinky application has the following dependencies in its pkg.yml file. This tells the build system to look in the base directory of repos/apache-mynewt-core for the libs/os , hw/hal , and libs/console/full packages. $ more apps/blinky/pkg.yml snip \npkg.deps:\n - @apache-mynewt-core/libs/os \n - @apache-mynewt-core/hw/hal \n - @apache-mynewt-core/libs/console/full", + "text": "The other major element of the Newt tool is the ability to create reusable source distributions from a collection of code. A project can be a reusable container of source code. In other words, projects can be versioned and redistributed, not packages. A project bundles together packages that are typically needed to work together in a product e.g. RTOS core, filesystem APIs, and networking stack. A project that has been made redistributable is known as a repository . \nRepositories can be added to your local project by adding them into your project.yml file. Here is an example of the blinky project's yml file which relies on apache-mynewt-core: $ more project.yml snip \nproject.repositories:\n - apache-mynewt-core\n\n# Use github s distribution mechanism for core ASF libraries.\n# This provides mirroring automatically for us.\n#\nrepository.apache-mynewt-core:\n type: github\n vers: 0-latest\n user: apache\n repo: incubator-mynewt-core When you specify this repository in the blinky's project file, you can then use the Newt tool to install dependencies: $ newt install\nDownloading repository description for apache-mynewt-core... success!\nDownloading repository incubator-mynewt-core (branch: develop) at \nhttps://github.com/apache/incubator-mynewt-core.git\nCloning into /var/folders/7l/7b3w9m4n2mg3sqmgw2q1b9p80000gn/T/newt-repo814721459 ...\nremote: Counting objects: 17601, done.\nremote: Compressing objects: 100% (300/300), done.\nremote: Total 17601 (delta 142), reused 0 (delta 0), pack-reused 17284\nReceiving objects: 100% (17601/17601), 6.09 MiB | 3.17 MiB/s, done.\nResolving deltas: 100% (10347/10347), done.\nChecking connectivity... done.\nRepos successfully installed Newt will install this repository in the /repos directory. In the case of blinky, the directory structure ends up looking like: $ tree -L 2\n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\ u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502 \u2514\u2500\u2500 blinky\n\u251c\u2500\u2500 project.state\n\u251c\u2500\u2500 project.yml\n\u251c\u2500\u2500 repos\n\u2502 \u2514\u2500\u2500 apache-mynewt-core\n\u2514\u2500\u2500 targets\n \u251c\u2500\u2500 my_blinky_sim\n \u2514\u2500\u2500 unittest In order to reference the installed repositories in packages, the \"@\" notation should be specified in the repository specifier. As an example, the apps/blinky application has the following dependencies in its pkg.yml file. This tells the build system to look in the base directory of repos/apache-mynewt-core for the kernel/os , hw/hal , and sys/console/full packages. $ more apps/blinky/pkg.yml snip \npkg.deps:\n - @apache-mynewt-core/kernel/os \n - @apache-mynewt-core/hw/hal \n - @apache-mynewt-core/sys/console/full", "title": "Source Management and Repositories" }, { @@ -10222,7 +10237,7 @@ }, { "location": "/newt/newt_operation/", - "text": "Newt Tool - Theory of Operations\n\n\nNewt has a fairly smart package manager that can read a directory tree, build a dependency tree, and emit the right build artifacts.\n\n\nBuilding dependencies\n\n\nNewt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop:\n\n\n$ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\n\u251c\u2500\u2500 apps\n\n\u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u2500\u2500 src\n\u251c\u2500\u2500 project.yml\n\n\u2514\u2500\u2500 targets\n\n \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files\n\n\ n\n\n\n\n\nWhen newt sees a directory tree that contains a \"project.yml\" file it knows that it is in the base directory of a project, and automatically builds a package tree. You can see that there are two essential package directories, \"apps\" and \"targets.\" \n\n\n\n\n\"apps\" Package Directory\n\n\napps\n is where applications are stored, and applications are where the main() function is contained. The base project directory comes with one simple app called \nblinky\n in the \napps\n directory. The core repository \n@apache-mynewt-core\n comes with many additional sample apps in its \napps\n directory. At the time of this writing, there are several example BLE apps, the boot app, slinky app for using newt manager protocol, and more in that directory.\n\n\n@~/dev/myproj$ ls repos/apache-mynewt-core/apps/\nblecent bleprph_oic bleuart ffs2native slinky_oic test\nblehci bletest boot ocf_sample spitest timtest\nbleprph bletiny fat2native sl inky splitty\n\n\n\n\n\nAlong with the \ntargets\n directory, \napps\n represents the top-level of the build tree for the particular project, and define the dependencies and features for the rest of the system. Mynewt users and developers can add their own apps to the project's \napps\n directory. \n\n\nThe app definition is contained in a \npkg.yml\n file. For example, blinky's \npkg.yml\n file is:\n\n\n$ more apps/blinky/pkg.yml\n\nsnip\n\npkg.name: apps/blinky\npkg.type: app\npkg.description: Basic example application which blinks an LED.\npkg.author: \nApache Mynewt \[email protected]\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.keywords:\n\npkg.deps:\n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/hw/hal\n\n - \n@apache-mynewt-core/sys/console/full\n\n\n\n\n\n\n\n\nThis file says that the name of the package is apps/blinky, and it \ndepends on kernel/os, hw/hal and sys/console/full packages.\n\n\nNOTE:\n @apache-mynewt-core is a repository descriptor, and this will be \ncovered in the \"repository\" section. \n\n\n\n\n\"targets\" Package Directory\n\n\ntargets\n is where targets are stored, and each target is a collection of parameters that must be passed to newt in order to generate a reproducible build. Along with the \napps\n directory, \ntargets\n represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies.\n\n\nMost targets consist of:\n\n\n\n\napp: The application to build\n\n\nbsp: The board support package to combine with that application\n\n\nbuild_profile: Either debug or optimized.\n\n\n\n\nThe \nmy_blinky_sim\n target that is included by default has the following settings:\n\n\n$ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\n$ ls targets/my_blinky_sim/\npkg.yml target.yml\n\n\n\n\n\nThere are helper functions to aid the developer specif y parameters for a target. \n\n\n\n\nvals\n: Displays all valid values for the specified parameter type (e.g. bsp for a target)\n\n\ntarget show\n: Displays the build artifacts for specified or all targets\n\n\n\n\nIn general, the three basic parameters of a target (\napp\n, \nbsp\n, and \nbuild_profile\n) are stored in the \ntarget.yml\n file in that target's build directory under \ntargets\n. You will also see a \npkg.yml\n file in the same directory. Since targets are packages, a \npkg.yml\n is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following:\n\n\n\n\nCflags: Any additional compiler flags you might want to specify to the build\n\n\nAflags: Any additional assembler flags you might want to specify to the build\n\n\nLflags: Any additional linker flags you might want to specify to the build\n\n\n\n\n\n\nResolving dependencies\n\n\nWhen newt is told to build a project, it will:\n\n\n\n\nfind the top-level project.yml fil e\n\n\nrecurse the packages in the package tree, and build a list of all \nsource packages\n\n\n\n\nNewt then looks at the target that the user set, for example, blinky_sim:\n\n\n$ more targets/my_blinky_sim/\npkg.yml target.yml\n$ more targets/my_blinky_sim/target.yml\n### Target: targets/my_blinky_sim\ntarget.app: \napps/blinky\n\ntarget.bsp: \n@apache-mynewt-core/hw/bsp/native\n\ntarget.build_profile: \ndebug\n\n\n\n\n\n\n\n\nThe target specifies two major things:\n\n\n\n\nApplication (target.app): The application to build\n\n\nBoard Support Package (target.bsp): The board support package to build \nalong with that application.\n\n\n\n\nNewt builds the dependency tree specified by all the packages. While building this tree, it does a few other things:\n\n\n\n\nSets up the include paths for each package. Any package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the\nnewt structure must always b e prefixed by the package name. For example, libs/os has the following include tree and its include directory files contains the package name \"os\" before any header files. This is so in order to avoid any header file conflicts.\n\n\n\n\n$ tree\n.\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 include\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 arch\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 cortex_m0\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u251c\u2500\u2500 cortex_m4\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 sim\n\u2502\u00a0\u00a0 \u2502\ u00a0\u00a0 \u2514\u2500\u2500 os\n\u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 endian.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_callout.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_cfg.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_eventq.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_heap.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_malloc.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_mbuf.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_mempool.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_mutex.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_sanity.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_sched.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_sem.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_task.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_test.h\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 os_time.h\n\u2502\u00a0\u00a0 \ u2514\u2500\u2500 queue.h\n\u251c\u2500\u2500 pkg.yml\n\u2514\u2500\u2500 src\n \u251c\u2500\u2500 arch\n\nsnip\n\n\n\n\n\n\n\n\n\n\n\n\nValidates API requirements. Packages can export APIs they \nimplement, (i.e. pkg.api: hw-hal-impl), and other packages can require \nthose APIs (i.e. pkg.req_api: hw-hal-impl).\n\n\n\n\n\n\nReads and validates the configuration setting definitions and values from the package \nsyscfg.yml\n files.\nIt generates a \nsyscfg.h\n header file that packages include in the source files inorder to access the settings.\n\nIt also generates a system initialization function to initialize the packages.\nSee \nSystem Configuration And Initialization\n for more information.\n\n\n\n\n\n\nIn order to properly resolve all dependencies in the build system, newt recursively processes the package dependencies until there are no new dependencies or features (because features can add dependencies.) And it builds a big list of all the packages that need to be build.\ n\n\nNewt then goes through this package list, and builds every package into \nan archive file.\n\n\nNOTE:\n The newt tool generates compiler dependencies for all of these packages, and only rebuilds the packages whose dependencies have changed. Changes in package \n project dependencies are also taken into account. It is smart, after all!\n\n\nProducing artifacts\n\n\nOnce newt has built all the archive files, it then links the archive files together. The linkerscript to use is specified by the board support package (BSP.)\n\n\nNOTE: One common use of the \"features\" option above is to overwrite \nwhich linkerscript is used, based upon whether or not the BSP is being \nbuild for a raw image, bootable image or bootloader itself.\n\n\nThe newt tool places all of it's artifacts into the bin/ directory at \nthe top-level of the project, prefixed by the target name being built, \nfor example:\n\n\n$ tree -L 4 bin/\nbin/\n\u2514\u2500\u2500 my_blinky_sim\n \u251c\u2500\u2500 apps\n \u2502 \u2514\u2500\u2500 blinky\n \u2502 \u251c\u2500\u2500 blinky.a\n \u2502 \u251c\u2500\u2500 blinky.a.cmd\n \u2502 \u251c\u2500\u2500 blinky.elf\n \u2502 \u251c\u2500\u2500 blinky.elf.cmd\n \u2502 \u251c\u2500\u2500 blinky.elf.dSYM\n \u2502 \u251c\u2500\u2500 blinky.elf.lst\n \u2502 \u251c\u2500\u2500 main.d\n \u2502 \u251c\u2500\u2500 main.o\n \u2502 \u2514\u2500\u2500 main.o.cmd\n \u251c\u2500\u2500 hw\n \u2502 \u251c\u2500\u2500 bsp\n \u2502 \u2502 \u2514\u2500\u2500 native\n \u2502 \u251c\u2500\u2500 hal\n \u2502 \u2502 \u251c\u2500\u2500 flash_map.d\n \u2502 \u2502 \u251c\u2500\u2500 flash_map.o\n\nsnip\n\n\n\n\n\n\n\n\nAs you can see, a number of files are generated:\n\n\n\n\nArchive File\n\n\n*.cmd: The command use to generate the object or archive file\n\n\n*.lst: The list file where symbols are located\n\n\n*.o The object files that g et put into the archive file\n\n\n\n\nDownload/Debug Support\n\n\nOnce a target has been build, there are a number of helper functions \nthat work on the target. These are:\n\n\n\n\nload\n Download built target to board\n\n\ndebug\n Open debugger session to target\n\n\nsize\n Size of target components\n\n\ncreate-image\n Add image header to target binary\n\n\nrun\n The equivalent of build, create-image, load, and debug on specified target\n\n\n\n\nload\n and \ndebug\n handles driving GDB and the system debugger. These \ncommands call out to scripts that are defined by the BSP.\n\n\n$ more repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh\n\nsnip\n\n. $CORE_PATH/hw/scripts/jlink.sh\n\nFILE_NAME=$BIN_BASENAME.elf\n\nif [ $# -gt 2 ]; then\n SPLIT_ELF_NAME=$3.elf\n # TODO -- this magic number 0x42000 is the location of the second image\n # slot. we should either get this from a flash map file or somehow learn\n # this from the image itself\n EXTRA_GDB_CMDS=\nadd-symbol-file $SPLIT_ELF_NAME 0x8000 -readnow\n\nfi\n\nJLINK_DEV=\nnRF52\n\n\njlink_debug\n\n\n\n\n\nThe idea is that every BSP will add support for the debugger environment \nfor that board. That way common tools can be used across various development boards and kits.", + "text": "Newt Tool - Theory of Operations\n\n\nNewt has a fairly smart package manager that can read a directory tree, build a dependency tree, and emit the right build artifacts.\n\n\nBuilding dependencies\n\n\nNewt can read a directory tree, build a dependency tree, and emit the right build artifacts. An example newt source tree is in incubator-mynewt-blinky/develop:\n\n\n$ tree -L 3 \n.\n\u251c\u2500\u2500 DISCLAIMER\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\n\u251c\u2500\u2500 apps\n\n\u2502 \u2514\u2500\u2500 blinky\n\u2502 \u251c\u2500\u2500 pkg.yml\n\u2502 \u2514\u2500\u2500 src\n\u251c\u2500\u2500 project.yml\n\n\u2514\u2500\u2500 targets\n\n \u251c\u2500\u2500 my_blinky_sim\n \u2502 \u251c\u2500\u2500 pkg.yml\n \u2502 \u2514\u2500\u2500 target.yml\n \u2514\u2500\u2500 unittest\n \u251c\u2500\u2500 pkg.yml\n \u2514\u2500\u2500 target.yml\n\n6 directories, 10 files\n\n\ n\n\n\n\n\nWhen newt sees a directory tree that contains a \"project.yml\" file it knows that it is in the base directory of a project, and automatically builds a package tree. You can see that there are two essential package directories, \"apps\" and \"targets.\" \n\n\n\n\n\"apps\" Package Directory\n\n\napps\n is where applications are stored, and applications are where the main() function is contained. The base project directory comes with one simple app called \nblinky\n in the \napps\n directory. The core repository \n@apache-mynewt-core\n comes with many additional sample apps in its \napps\n directory. At the time of this writing, there are several example BLE apps, the boot app, slinky app for using newt manager protocol, and more in that directory.\n\n\n@~/dev/myproj$ ls repos/apache-mynewt-core/apps/\nblecent blesplit boot sensors_test splitty\nblehci bletest fat2native slinky test\nbleprph bletiny ffs2native slinky_oic testbench\ nbleprph_oic bleuart ocf_sample spitest timtest\n\n\n\n\n\nAlong with the \ntargets\n directory, \napps\n represents the top-level of the build tree for the particular project, and define the dependencies for the rest of the system. Mynewt users and developers can add their own apps to the project's \napps\n directory. \n\n\nThe app definition is contained in a \npkg.yml\n file. For example, blinky's \npkg.yml\n file is:\n\n\n$ more apps/blinky/pkg.yml\n\nsnip\n\npkg.name: apps/blinky\npkg.type: app\npkg.description: Basic example application which blinks an LED.\npkg.author: \nApache Mynewt \[email protected]\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.keywords:\n\npkg.deps:\n - \n@apache-mynewt-core/kernel/os\n\n - \n@apache-mynewt-core/hw/hal\n\n - \n@apache-mynewt-core/sys/console/full\n\n\n\n\n\n\n\n\nThis file says that the name of the package is apps/blinky, and it depends on the \nkernel/os,\nhw/hal\nand\nsys/console/full` packages. \n\n\nNOTE:\n @apache-mynewt-core is a repository descriptor, and this will be \ncovered in the \"repository\" section. \n\n\n\n\n\"targets\" Package Directory\n\n\ntargets\n is where targets are stored, and each target is a collection of parameters that must be passed to newt in order to generate a reproducible build. Along with the \napps\n directory, \ntargets\n represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies.\n\n\nMost targets consist of:\n\n\n\n\napp: The application to build\n\n\nbsp: The board support package to combine with that application\n\n\nbuild_profile: Either debug or optimized.\n\n\n\n\nThe \nmy_blinky_sim\n target that is included by default has the following settings:\n\n\n$ newt target show\ntargets/my_blinky_sim\n app=apps/blinky\n bsp=@apache-mynewt-core/hw/bsp/native\n build_profile=debug\n$ ls targets/my_blinky_sim/\npkg.yml target.yml\n\n\n\n\n\nThere are helper fun ctions to aid the developer specify parameters for a target. \n\n\n\n\nvals\n: Displays all valid values for the specified parameter type (e.g. bsp for a target)\n\n\ntarget show\n: Displays the variable values for either a specific target or all targets defined for the project\n\n\ntarget set\n: Sets values for target variables\n\n\n\n\nIn general, the three basic parameters of a target (\napp\n, \nbsp\n, and \nbuild_profile\n) are stored in the target's \ntarget.yml\n file in the targets/\ntarget-name\n directory, where \ntarget-name\n is the name of the target. You will also see a \npkg.yml\n file in the same directory. Since targets are packages, a \npkg.yml\n is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following:\n\n\n\n\nCflags: Any additional compiler flags you might want to specify to the build\n\n\nAflags: Any additional assembler flags you might want to specify to the build\n\n\nLflags: Any additional linker fla gs you might want to specify to the build\n\n\n\n\nYou can also override the values of the system configuration settings that are defined by the packages that your target includes. You override the values in your target's \nsyscfg.yml\n file (stored in the targets/\ntarget-name\n directory). You can use the \nnewt target config show\n command to see the configuration settings and values for your target, and use the \nnewt target set\n command to set the \nsyscfg\n variable and override the configuration setting values. You can also use an editor to create your target's \nsyscfg.yml\n file and add the setting values to the file. See \nSystem Configuration And Initialization\n for more information on system configuration settings.\n\n\n\n\nResolving dependencies\n\n\nWhen newt builds a project, it will:\n\n\n\n\nfind the top-level project.yml file\n\n\nrecurse the packages in the package tree, and build a list of all \nsource packages\n\n\n\n\nNewt then looks at the target that the user set, for example, blinky_sim:\n\n\n$ more targets/my_blinky_sim/\npkg.yml target.yml\n$ more targets/my_blinky_sim/target.yml\n### Target: targets/my_blinky_sim\ntarget.app: \napps/blinky\n\ntarget.bsp: \n@apache-mynewt-core/hw/bsp/native\n\ntarget.build_profile: \ndebug\n\n\n\n\n\n\n\n\nThe target specifies two major things:\n\n\n\n\nApplication (target.app): The application to build\n\n\nBoard Support Package (target.bsp): The board support package to build \nalong with that application.\n\n\n\n\nNewt builds the dependency tree specified by all the packages. While building this tree, it does a few other things:\n\n\n\n\nSets up the include paths for each package. Any package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the\nnewt structure must always be prefixed by the package name. For example, kernel/os has the following include tree and its include directory files contains the package name \"os\" before any header files. This is so in order to avoid any header file conflicts.\n\n\n\n\n$tree kernel/os/include\nkernel/os/include\n\u2514\u2500\u2500 os\n \u251c\u2500\u2500 arch\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 cortex_m0\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 cortex_m4\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os\n \u2502\u00a0\u00a0 \u2502\u00a0\u00a0 \u2514\u2500\u2500 os_arch.h\n \u2502\u00a0\u00a0 \u251c\u2500\
<TRUNCATED>
