Repository: incubator-mynewt-site Updated Branches: refs/heads/asf-site 8da4f0a34 -> 6de9da2b5
updated newt intro, operation Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/6de9da2b Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/6de9da2b Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/6de9da2b Branch: refs/heads/asf-site Commit: 6de9da2b584171968e82096588d4ddf85e93c605 Parents: 8da4f0a Author: aditihilbert <[email protected]> Authored: Tue Dec 20 00:07:28 2016 -0800 Committer: aditihilbert <[email protected]> Committed: Tue Dec 20 00:07:28 2016 -0800 ---------------------------------------------------------------------- mkdocs/search_index.json | 14 +++--- newt/newt_intro/index.html | 3 +- newt/newt_operation/index.html | 91 +++++++++++++++++-------------------- 3 files changed, 50 insertions(+), 58 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6de9da2b/mkdocs/search_index.json ---------------------------------------------------------------------- diff --git a/mkdocs/search_index.json b/mkdocs/search_index.json index e221b20..9eaebb4 100644 --- a/mkdocs/search_index.json +++ b/mkdocs/search_index.json @@ -7022,7 +7022,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\ndownload\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\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 t ool 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\u2500 NOTICE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 apps\n\u2502 \u2514\u 2500\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", + "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", "title": "toc" }, { @@ -7047,7 +7047,7 @@ }, { "location": "/newt/newt_intro/#more-operations-using-newt", - "text": "Once a target has been built, Newt allows additional operations on the target. download : 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 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 For more details on how Newt works, go to Newt - Theory of Operations .", "title": "More operations using Newt" }, { @@ -7057,7 +7057,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. Along with the \ntargets\n directory, \napps\n represents the top-level of the build tree, and define the dependencies and features for the rest of the system.\n\n\nThe app definition is contained in a \npkg.yml\n file. An example of blinky's \npkg.yml\n file is:\n\n\n$ more apps/blinky/pkg.yml\n\nsnip\n\npkg.name: apps/blinky\npkg.vers: 0.8.0\npkg.description: Basic example application which blinks an LED.\npkg.author: \nApache Mynewt \[email protected]\n\npkg.homepage: \nhttp://mynewt.apache.org/\n\npkg.repository:\npkg.keywords:\n\npkg.deps:\n - \n@apache-myn ewt-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\nThis file says that the name of the package is apps/blinky, and it \ndepends on libs/os, hw/hal and libs/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 in the example below has t he 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 my_blinky_sim/\npkg.yml target.yml\n\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\nfeatures: Any system level features you want to enable.\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 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 goes and builds the dependency tree specified by all the packages. While building this tree, it does a few other things:\n\n\n\n\nAny package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the\nne wt structure must always be 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\u25 02\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\nAPI requirements are validated. 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\n\"Features\" options are supported. Packages can change what dependencies \nthey have, or what flags they are using based upon what features are enabled in the system. As an example, many packages will add additional software, based on whether the shell package is present. To do this, they can overwrite cflags or deps based upon the shell \"feature.\"\n\n\n\n\n\n\npkg.cflags.SHELL: -DSHELL_PRESENT\n\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 b uilds 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\u25 14\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 fil e where symbols are located\n\n\n*.o The object files that get 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\ndownload\n Download built target to board\n\n\ndebug\n Open debugger session to target\n\n\nsize Size of target components\n\n\ncreate-image Add image header to target binary\n\n\n\n\nDownload and debug 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/nrf52pdk/nrf52pdk_debug.sh\n\nsnip\n\n#\nif [ $# -lt 1 ]; then\n echo \nNeed binary to download\n\n exit 1\nfi\n\nFILE_NAME=$2.elf\nGDB_CMD_FILE=.gdb_cmds\n\necho \nDebugging\n $FILE_NAME\n\n# Monitor mode. Background process gets it\ns own process group.\nset -m\nJLinkGDBServer -device nRF52 -speed 4000 -if SWD -port 3333 -singlerun \n\nset +m\n\necho \ntarget remo te localhost:3333\n \n $GDB_CMD_FILE\n\narm-none-eabi-gdb -x $GDB_CMD_FILE $FILE_NAME\n\nrm $GDB_CMD_FILE\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.\n\n\nNOTE:\n Both for compiler definitions and debugger scripts, the plan is to \ncreate Dockerizable containers of these toolchains. This should make \nthings much easier to support across Mac OS X, Linux and Windows. Newt \nwill know how to call out to Docker to perform these processes.", + "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 goes and builds the dependency tree specified by all the packages. While building this tree, it does a few other things:\n\n\n\n\nAny 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, 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\u 2500\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\nAPI requirements are validated. 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\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\u250 0 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 get 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.", "title": "Newt Theory of Ops" }, { @@ -7072,17 +7072,17 @@ }, { "location": "/newt/newt_operation/#apps-package-directory", - "text": "apps is where applications are stored, and applications are where the main() function is contained. Along with the targets directory, apps represents the top-level of the build tree, and define the dependencies and features for the rest of the system. The app definition is contained in a pkg.yml file. An example of blinky's pkg.yml file is: $ more apps/blinky/pkg.yml snip \npkg.name: apps/blinky\npkg.vers: 0.8.0\npkg.description: Basic example application which blinks an LED.\npkg.author: Apache Mynewt [email protected] \npkg.homepage: http://mynewt.apache.org/ \npkg.repository:\npkg.keywords:\n\npkg.deps:\n - @apache-mynewt-core/libs/os \n - @apache-mynewt-core/hw/hal \n - @apache-mynewt-core/libs/console/full This file says that the name of the package is apps/blinky, and it \ndepends on libs/os, hw/hal and libs/console/full packages. NOTE: @apache-mynewt-core is a repository descriptor, and this will be \ncover ed in the \"repository\" section.", + "text": "apps is where applications are stored, and applications are where the main() function is contained. The base project directory comes with one simple app called blinky in the apps directory. The core repository @apache-mynewt-core comes with many additional sample apps in its apps 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. @~/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 slinky splitty Along with the targets directory, apps 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 apps directory. The app definition is contained in a pkg.yml file. For example, blinky's pkg.yml file is: $ more apps/blinky/pkg.yml snip \npkg.name: apps/blinky\npkg.type: app\npkg.description: Basic example application which blinks an LED.\npkg.author: Apache Mynewt [email protected] \npkg.homepage: http://mynewt.apache.org/ \npkg.keywords:\n\npkg.deps:\n - @apache-mynewt-core/kernel/os \n - @apache-mynewt-core/hw/hal \n - @apache-mynewt-core/sys/console/full This file says that the name of the package is apps/blinky, and it \ndepends on kernel/os, hw/hal and sys/console/full packages. NOTE: @apache-mynewt-core is a repository descriptor, and this will be \ncovered in the \"repository\" section.", "title": "\"apps\" Package Directory" }, { "location": "/newt/newt_operation/#targets-package-directory", - "text": "targets 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 apps directory, targets represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies. Most targets consist of: app: The application to build bsp: The board support package to combine with that application build_profile: Either debug or optimized. The my_blinky_sim target in the example below has the following settings: $ 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 my_blinky_sim/\npkg.yml target.yml In general, the three basic parameters of a target ( app , bsp , and build_profile ) are stored in the target.yml file in that target's build directory under targets . You will also see a pkg.yml file in the same direct ory. Since targets are packages, a pkg.yml is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following: Cflags: Any additional compiler flags you might want to specify to the build Aflags: Any additional assembler flags you might want to specify to the build Lflags: Any additional linker flags you might want to specify to the build features: Any system level features you want to enable.", + "text": "targets 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 apps directory, targets represents the top of the build tree. Any packages or parameters specified at the target level cascades down to all dependencies. Most targets consist of: app: The application to build bsp: The board support package to combine with that application build_profile: Either debug or optimized. The my_blinky_sim target that is included by default has the following settings: $ 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 There are helper functions to aid the developer specify parameters for a target. vals : Displays all valid values for the specified parameter type (e.g. bsp for a target) target show : Displays the build art ifacts for specified or all targets In general, the three basic parameters of a target ( app , bsp , and build_profile ) are stored in the target.yml file in that target's build directory under targets . You will also see a pkg.yml file in the same directory. Since targets are packages, a pkg.yml is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following: Cflags: Any additional compiler flags you might want to specify to the build Aflags: Any additional assembler flags you might want to specify to the build Lflags: Any additional linker flags you might want to specify to the build", "title": "\"targets\" Package Directory" }, { "location": "/newt/newt_operation/#resolving-dependencies", - "text": "When newt is told to build a project, it will: find the top-level project.yml file recurse the packages in the package tree, and build a list of all \nsource packages Newt then looks at the target that the user set, for example, blinky_sim: $ 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: apps/blinky \ntarget.bsp: @apache-mynewt-core/hw/bsp/native \ntarget.build_profile: debug The target specifies two major things: Application (target.app): The application to build Board Support Package (target.bsp): The board support package to build \nalong with that application. Newt goes and builds the dependency tree specified by all the packages. While building this tree, it does a few other things: Any package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the\nnewt structure mus t always be 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. $ 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 \u25 02\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 snip API requirements are validated. 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). \"Features\" options are supported. Packages can change what dependencies \nthey have, or what flags they are using based upon what features are enabled in the system. As an example, many packages will add additional software, based on whether the shell package is present. To do this, they can overwrite cflags or deps based upon the shell \"feature.\" pkg.cflags.SHELL: -DSHELL_PRESENT In 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. Newt then goes thr ough this package list, and builds every package into \nan archive file. NOTE: The Newt tool generates compiler dependencies for all of these packages, and only rebuilds the packages whose dependencies have changed. Changes in package project dependencies are also taken into account. It is smart, after all!", + "text": "When newt is told to build a project, it will: find the top-level project.yml file recurse the packages in the package tree, and build a list of all \nsource packages Newt then looks at the target that the user set, for example, blinky_sim: $ 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: apps/blinky \ntarget.bsp: @apache-mynewt-core/hw/bsp/native \ntarget.build_profile: debug The target specifies two major things: Application (target.app): The application to build Board Support Package (target.bsp): The board support package to build \nalong with that application. Newt goes and builds the dependency tree specified by all the packages. While building this tree, it does a few other things: Any package that depends on another package, automatically gets the include directories from the package it includes. Include directories in the\nnewt structure mus t always be 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. $ 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 \u25 02\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 snip API requirements are validated. 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). In 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. Newt then goes through this package list, and builds every package into \nan archive file. NOTE: The Newt tool generates compiler dependencies for all of these packages, and only rebuilds the packages whose dependencies have changed. Changes in package project dependencies are also taken into account. It is smart, after all!", "title": "Resolving dependencies" }, { @@ -7092,7 +7092,7 @@ }, { "location": "/newt/newt_operation/#downloaddebug-support", - "text": "Once a target has been build, there are a number of helper functions \nthat work on the target. These are: download Download built target to board debug Open debugger session to target size Size of target components create-image Add image header to target binary Download and debug handles driving GDB and the system debugger. These \ncommands call out to scripts that are defined by the BSP. $ more repos/apache-mynewt-core/hw/bsp/nrf52pdk/nrf52pdk_debug.sh snip \n#\nif [ $# -lt 1 ]; then\n echo Need binary to download \n exit 1\nfi\n\nFILE_NAME=$2.elf\nGDB_CMD_FILE=.gdb_cmds\n\necho Debugging $FILE_NAME\n\n# Monitor mode. Background process gets it s own process group.\nset -m\nJLinkGDBServer -device nRF52 -speed 4000 -if SWD -port 3333 -singlerun \nset +m\n\necho target remote localhost:3333 $GDB_CMD_FILE\n\narm-none-eabi-gdb -x $GDB_CMD_FILE $FILE_NAME\n\nrm $GDB_CMD_FILE The 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. NOTE: Both for compiler definitions and debugger scripts, the plan is to \ncreate Dockerizable containers of these toolchains. This should make \nthings much easier to support across Mac OS X, Linux and Windows. Newt \nwill know how to call out to Docker to perform these processes.", + "text": "Once a target has been build, there are a number of helper functions \nthat work on the target. These are: load Download built target to board debug Open debugger session to target size Size of target components create-image Add image header to target binary run The equivalent of build, create-image, load, and debug on specified target load and debug handles driving GDB and the system debugger. These \ncommands call out to scripts that are defined by the BSP. $ more repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh snip \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= add-symbol-file $SPLIT_ELF_NAME 0x8000 -readnow \nfi\n\nJLINK_DEV= nRF52 \n \njlink_debug The 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.", "title": "Download/Debug Support" }, { http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6de9da2b/newt/newt_intro/index.html ---------------------------------------------------------------------- diff --git a/newt/newt_intro/index.html b/newt/newt_intro/index.html index eed9439..f390529 100644 --- a/newt/newt_intro/index.html +++ b/newt/newt_intro/index.html @@ -429,10 +429,11 @@ bin <h3 id="more-operations-using-newt">More operations using Newt</h3> <p>Once a target has been built, Newt allows additional operations on the target. </p> <ul> -<li><strong>download</strong>: Download built target to board</li> +<li><strong>load</strong>: Download built target to board</li> <li><strong>debug</strong>: Open debugger session to target</li> <li><strong>size</strong>: Get size of target components</li> <li><strong>create-image</strong>: Add image header to the binary image</li> +<li><strong>run</strong>: Build, create image, load, and finally open a debug session with the target</li> </ul> <p>For more details on how Newt works, go to <a href="../newt_operation/">Newt - Theory of Operations</a>.</p> <p><br></p> http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6de9da2b/newt/newt_operation/index.html ---------------------------------------------------------------------- diff --git a/newt/newt_operation/index.html b/newt/newt_operation/index.html index 1cf479d..d35fff0 100644 --- a/newt/newt_operation/index.html +++ b/newt/newt_operation/index.html @@ -376,28 +376,35 @@ <p>When 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." </p> <p><br></p> <h4 id="apps-package-directory">"apps" Package Directory</h4> -<p><code>apps</code> is where applications are stored, and applications are where the main() function is contained. Along with the <code>targets</code> directory, <code>apps</code> represents the top-level of the build tree, and define the dependencies and features for the rest of the system.</p> -<p>The app definition is contained in a <code>pkg.yml</code> file. An example of blinky's <code>pkg.yml</code> file is:</p> +<p><code>apps</code> is where applications are stored, and applications are where the main() function is contained. The base project directory comes with one simple app called <code>blinky</code> in the <code>apps</code> directory. The core repository <code>@apache-mynewt-core</code> comes with many additional sample apps in its <code>apps</code> 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.</p> +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">@~/dev/myproj$ ls repos/apache-mynewt-core/apps/ +blecent bleprph_oic bleuart ffs2native slinky_oic test +blehci bletest boot ocf_sample spitest timtest +bleprph bletiny fat2native slinky splitty +</pre></div> + + +<p>Along with the <code>targets</code> directory, <code>apps</code> 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 <code>apps</code> directory. </p> +<p>The app definition is contained in a <code>pkg.yml</code> file. For example, blinky's <code>pkg.yml</code> file is:</p> <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ more apps/blinky/pkg.yml <snip> pkg.name: apps/blinky -pkg.vers: 0.8.0 +pkg.type: app pkg.description: Basic example application which blinks an LED. pkg.author: "Apache Mynewt <[email protected]>" pkg.homepage: "http://mynewt.apache.org/" -pkg.repository: pkg.keywords: pkg.deps: - - "@apache-mynewt-core/libs/os" - - "@apache-mynewt-core/hw/hal" - - "@apache-mynewt-core/libs/console/full" + - "@apache-mynewt-core/kernel/os" + - "@apache-mynewt-core/hw/hal" + - "@apache-mynewt-core/sys/console/full" </pre></div> <p><br></p> <p>This file says that the name of the package is apps/blinky, and it -depends on libs/os, hw/hal and libs/console/full packages.</p> +depends on kernel/os, hw/hal and sys/console/full packages.</p> <p><strong>NOTE:</strong> @apache-mynewt-core is a repository descriptor, and this will be covered in the "repository" section. </p> <p><br></p> @@ -409,23 +416,27 @@ covered in the "repository" section. </p> <li>bsp: The board support package to combine with that application</li> <li>build_profile: Either debug or optimized.</li> </ul> -<p>The <code>my_blinky_sim</code> target in the example below has the following settings:</p> +<p>The <code>my_blinky_sim</code> target that is included by default has the following settings:</p> <div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ newt target show targets/my_blinky_sim app=apps/blinky bsp=@apache-mynewt-core/hw/bsp/native build_profile=debug -$ ls my_blinky_sim/ +$ ls targets/my_blinky_sim/ pkg.yml target.yml </pre></div> +<p>There are helper functions to aid the developer specify parameters for a target. </p> +<ul> +<li><strong>vals</strong>: Displays all valid values for the specified parameter type (e.g. bsp for a target)</li> +<li><strong>target show</strong>: Displays the build artifacts for specified or all targets</li> +</ul> <p>In general, the three basic parameters of a target (<code>app</code>, <code>bsp</code>, and <code>build_profile</code>) are stored in the <code>target.yml</code> file in that target's build directory under <code>targets</code>. You will also see a <code>pkg.yml</code> file in the same directory. Since targets are packages, a <code>pkg.yml</code> is expected. It contains typical package descriptors, dependencies, and additional parameters such as the following:</p> <ul> <li>Cflags: Any additional compiler flags you might want to specify to the build</li> <li>Aflags: Any additional assembler flags you might want to specify to the build</li> <li>Lflags: Any additional linker flags you might want to specify to the build</li> -<li>features: Any system level features you want to enable.</li> </ul> <p><br></p> <h3 id="resolving-dependencies">Resolving dependencies</h3> @@ -499,21 +510,10 @@ newt structure must always be prefixed by the package name. For example, libs/os <p><br></p> <ul> -<li> -<p>API requirements are validated. Packages can export APIs they +<li>API requirements are validated. Packages can export APIs they implement, (i.e. pkg.api: hw-hal-impl), and other packages can require -those APIs (i.e. pkg.req_api: hw-hal-impl).</p> -</li> -<li> -<p>"Features" options are supported. Packages can change what dependencies -they have, or what flags they are using based upon what features are enabled in the system. As an example, many packages will add additional software, based on whether the shell package is present. To do this, they can overwrite cflags or deps based upon the shell "feature."</p> -</li> +those APIs (i.e. pkg.req_api: hw-hal-impl).</li> </ul> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">pkg.cflags.SHELL: -DSHELL_PRESENT -</pre></div> - - -<p><br></p> <p>In 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.</p> <p>Newt then goes through this package list, and builds every package into an archive file.</p> @@ -562,45 +562,36 @@ bin/ <p>Once a target has been build, there are a number of helper functions that work on the target. These are:</p> <ul> -<li><strong>download</strong> Download built target to board</li> +<li><strong>load</strong> Download built target to board</li> <li><strong>debug</strong> Open debugger session to target</li> -<li>size Size of target components</li> -<li>create-image Add image header to target binary</li> +<li><strong>size</strong> Size of target components</li> +<li><strong>create-image</strong> Add image header to target binary</li> +<li><strong>run</strong> The equivalent of build, create-image, load, and debug on specified target</li> </ul> -<p>Download and debug handles driving GDB and the system debugger. These +<p><code>load</code> and <code>debug</code> handles driving GDB and the system debugger. These commands call out to scripts that are defined by the BSP.</p> -<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ more repos/apache-mynewt-core/hw/bsp/nrf52pdk/nrf52pdk_debug.sh +<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">$ more repos/apache-mynewt-core/hw/bsp/nrf52dk/nrf52dk_debug.sh <snip> -# -if [ $# -lt 1 ]; then - echo "Need binary to download" - exit 1 -fi +. $CORE_PATH/hw/scripts/jlink.sh -FILE_NAME=$2.elf -GDB_CMD_FILE=.gdb_cmds +FILE_NAME=$BIN_BASENAME.elf -echo "Debugging" $FILE_NAME - -# Monitor mode. Background process gets it's own process group. -set -m -JLinkGDBServer -device nRF52 -speed 4000 -if SWD -port 3333 -singlerun & -set +m - -echo "target remote localhost:3333" > $GDB_CMD_FILE +if [ $# -gt 2 ]; then + SPLIT_ELF_NAME=$3.elf + # TODO -- this magic number 0x42000 is the location of the second image + # slot. we should either get this from a flash map file or somehow learn + # this from the image itself + EXTRA_GDB_CMDS="add-symbol-file $SPLIT_ELF_NAME 0x8000 -readnow" +fi -arm-none-eabi-gdb -x $GDB_CMD_FILE $FILE_NAME +JLINK_DEV="nRF52" -rm $GDB_CMD_FILE +jlink_debug </pre></div> <p>The idea is that every BSP will add support for the debugger environment for that board. That way common tools can be used across various development boards and kits.</p> -<p><strong>NOTE:</strong> Both for compiler definitions and debugger scripts, the plan is to -create Dockerizable containers of these toolchains. This should make -things much easier to support across Mac OS X, Linux and Windows. Newt -will know how to call out to Docker to perform these processes.</p> <div class="row">
