Repository: incubator-mynewt-site Updated Branches: refs/heads/develop 6a3585eb9 -> e06d279c8
Updated newt command reference including newt complete, mfg, and target 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/de74428b Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/de74428b Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/de74428b Branch: refs/heads/develop Commit: de74428b6e8f9bdd76b93ce26ca6eff32b40826f Parents: 6a3585e Author: aditihilbert <[email protected]> Authored: Mon Jan 2 13:04:00 2017 -0800 Committer: aditihilbert <[email protected]> Committed: Mon Jan 2 13:04:00 2017 -0800 ---------------------------------------------------------------------- docs/newt/command_list/newt_complete.md | 31 ++++++++ docs/newt/command_list/newt_mfg.md | 103 +++++++++++++++++++++++++++ docs/newt/command_list/newt_target.md | 32 +++++---- docs/newt/newt_ops.md | 51 ++++++------- mkdocs.yml | 2 + 5 files changed, 181 insertions(+), 38 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/de74428b/docs/newt/command_list/newt_complete.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_complete.md b/docs/newt/command_list/newt_complete.md new file mode 100644 index 0000000..7f2d55c --- /dev/null +++ b/docs/newt/command_list/newt_complete.md @@ -0,0 +1,31 @@ +## <font color="#F2853F" style="font-size:24pt">newt complete </font> + +Performs bash autocompletion using tab. It is not intended to be called directly from the command line. + +#### Install bash autocompletion + +```no-highlight + $ brew install bash-completion + Updating Homebrew... + <snip> + Bash completion has been installed to: + /usr/local/etc/bash_completion.d + ==> Summary + ðº /usr/local/Cellar/bash-completion/1.3_1: 189 files, 607.8K +``` + +#### Enable autocompletion for newt + +```no-highlight + $ complete -C "newt complete" newt +``` + +#### Usage + +Hit tab and see possible completion options or completed command. + +```no-highlight + $ newt target s + set show + $ newt target show +``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/de74428b/docs/newt/command_list/newt_mfg.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_mfg.md b/docs/newt/command_list/newt_mfg.md new file mode 100644 index 0000000..f8e5b51 --- /dev/null +++ b/docs/newt/command_list/newt_mfg.md @@ -0,0 +1,103 @@ +## <font color="#F2853F" style="font-size:24pt">newt mfg </font> + +Provides commands to create, build, and upload manufacturing image. + +#### Usage: + +```no-highlight + newt mfg [flags] + newt mfg [command] +``` +#### Available Commands: + +```no-highlight + create Create a manufacturing flash image + deploy Builds and uploads a manufacturing image (build + load) + load Load a manufacturing flash image onto a device +``` + +#### Flags: + +```no-highlight + -h, --help=false: help for mfg +``` + +#### Global Flags: + +```no-highlight + -l, --loglevel="WARN": Log level, defaults to WARN. + -o, --outfile string Filename to tee log output to + -q, --quiet=false: Be quiet; only display error output. + -s, --silent=false: Be silent; don't output anything. + -v, --verbose=false: Enable verbose output when executing commands. +``` +#### Description + +Sub-command | Explanation +-------------| ------------------------ +create | A manufacturing image specifies 1) a boot loader target, and 2) one or more image targets. Assuming the manufacturing entity has been created and defined in the `mfgs/<mfg image name>/` package(see Examples below), this command collects the manufacturing related files in the newly created `bin/mfgs/<mfg image name>` directory. The collection includes manifests with the image build time, version, manufacturing package build time, image ID (or hash) etc. It is essentially a snapshot of the image data and metadata uploaded to the device flash at manufacturing time. Note that the command expects the targets and images to have already been built using `newt build` and `newt create-image` commands. +deploy | A combination of build and load commands to put together and upload manufacturing image on to the device. +load | Loads the manufacturing package onto to the flash of the connected device. + + +#### Examples + +Suppose you have created two targets (one for the bootloader and one for the `blinky` app). + +```no-highlight +$ newt target show +targets/my_blinky_sim + app=apps/blinky + bsp=@apache-mynewt-core/hw/bsp/native + build_profile=debug +targets/rb_blinky + app=apps/blinky + bsp=@apache-mynewt-core/hw/bsp/rb-nano2 + build_profile=debug +targets/rb_boot + app=@apache-mynewt-core/apps/boot + bsp=@apache-mynewt-core/hw/bsp/rb-nano2 + build_profile=optimized +``` + +Build the bootloader and app images. + +``` +$ newt build rb_boot +$ newt build rb_boot +$ newt create-image rb_blinky 0.0.1 +``` + +Create the directory and package to hold the manufacturing images. + +``` +$ mkdir -p mfgs/rb_blinky_rsa +``` + +The `rb_blinky_rsa` package needs a pkg.yml file. In addition it is needs a mfg.yml file where the two constituent targets are defined. An example of each file is shown below. + +``` +$ more mfgs/rb_blinky_rsa/pkg.yml +pkg.name: "mfgs/rb_blinky_rsa" +pkg.type: "mfg" +pkg.description: +pkg.author: +pkg.homepage: +``` + +``` +$ more mfgs/rb_blinky_rsa/mfg.yml +mfg.bootloader: 'targets/rb_boot' +mfg.images: + - 'targets/rb_blinky' +``` + +Run the `newt mfg create` command to collect all the manufacturing snapshot files. + +``` +$ newt mfg create rb_blinky_rsa +Creating a manufacturing image from the following files: +<snip> +Generated the following files: +<snip> +$ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/de74428b/docs/newt/command_list/newt_target.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_target.md b/docs/newt/command_list/newt_target.md index 2921506..82130cb 100644 --- a/docs/newt/command_list/newt_target.md +++ b/docs/newt/command_list/newt_target.md @@ -9,12 +9,14 @@ Provides commands to create, build, delete, and query targets. ``` #### Available Commands: ```no-highlight - show View target configuration variables - set Set target configuration variable + config View target system configuration + copy Copy target create Create a target delete Delete target - copy Copy target - vars Show variable names possible for a target + dep View target's dependency graph + revdep View target's reverse-dependency graph + set Set target configuration variable + show View target configuration variables ``` #### Flags: @@ -36,24 +38,26 @@ Provides commands to create, build, delete, and query targets. Sub-command | Explanation -------------| ------------------------ -show | Shows what variables (attributes) are set on the specified target `input1`. If no `input1` is specified then show the configuration for all the targets defined so far. -set | Set variables (attributes) of the target named via `input1`. Currently the list of possible attributes (variables) are:`app`, `bsp`, `build_profile`, `features`, `cflags`, `lflags`. For a simulated target, e.g. for software testing purposes, `bsp` is set to `@apache-mynewt-core/hw/bsp/native`. - | To display all the existing values for a target variable (attribute), you can simply hit return after that variable. For example, `newt target set input1 app` displays the valid values available for the variable `app` for a target named `input11`. - | Currently, the only two values available for `build_profile` are `optimized` and `debug`. +config | Displays the specified target's system configuration. The configuration for any package is listed in its `syscfg.yml` file. A target build consists of several packages. The command lists the settings for the config variables from all the included packages. If the default values have not been changed then the default values will be seen. +copy | Set variables (attributes) of the target named via `input1`. Currently the list of possible attributes (variables) are:`app`, `bsp`, `build_profile`, `cflags`, `lflags`. For a simulated target, e.g. for software testing purposes, `bsp` is set to `@apache-mynewt-core/hw/bsp/native`. create | Creates an empty target definition by the name of `input1`. -delete | Deletes only the description for the target. Does not delete the target directory with associated binaries. If you want to clean out the binaries, list files, and executables use`newt target clean <target-name>` **before** deleting the target! -copy | Creates a new target by the name of `input2` by cloning the definition of an existing target named `input1`. -vars | Shows what variables (attributes) are available to set on the target +delete | Deletes only the description for the target. Does not delete the target directory with associated binaries. If you want to clean out the binaries, list files, and executables use`newt clean <target-name>` **before** deleting the target! +dep | Creates dependency tree for packages in the code for a target. Display shows each package followed by the list of libraries or packages that it depends on. +revdep | Creates the reverse dependency tree for packages in the code for a target. Display shows each package followed by the list of libraries or packages that depend on it. +set | Set variables (attributes) of the target named via `input1`. Currently the list of possible attributes (variables) are:`app`, `bsp`, `build_profile`, `features`, `cflags`, `lflags`. For a simulated target, e.g. for software testing purposes, `bsp` is set to `@apache-mynewt-core/hw/bsp/native`. + | To display all the existing values for a target variable (attribute), you can issue a `newt vals <variable-name>` command. For example, `newt vals app` displays the valid values available for the variable `app` for any target. + | Currently, the only two values available for `build_profile` are `optimized` and `debug`. +show | Shows what variables (attributes) are set on the specified target `input1`. If no `input1` is specified then show the configuration for all the targets defined so far. #### Examples Sub-command | Usage | Explanation -------------| -----------------------|----------------- +config | newt target config rb_blinky | Shows all the system configuration settings for all the packages in the target named `rb_blinky`. +copy | newt target copy rb_blinky rb_bletiny | Clones the target settings in `rb_blinky` to the destination target `rb_bletiny` +create | newt target create target1 | Creates an empty target by the name `target1` show | newt target show myble | Shows all variable settings for the target named "myble" i.e. what app, bsp, build_profile, features, cflags are set to. Note that all variables are not required to be set in order to successfully define a target. show | newt target show | Shows all variable settings for all the targets defined. set | newt target set myble app=@apache-mynewt-core/apps/bletiny | Assign `bletiny` to be the application to be included in the build for the target named `myble`. -copy | newt target copy my_blinky_sim test1 | Creates a new target by the name `test1` by copying the attributes from `my_blinky_sim` -vars | newt target vars | Shows all the variables newt recognizes - app, bsp, build_profile, features - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/de74428b/docs/newt/newt_ops.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_ops.md b/docs/newt/newt_ops.md index 69ec16f..113968f 100644 --- a/docs/newt/newt_ops.md +++ b/docs/newt/newt_ops.md @@ -10,35 +10,38 @@ For instance, in the example below, the *newt* command has the subcommand `targe Global flags work uniformly across *newt* commands. Consider the flag `-v, --verbose,` It works both for command and subcommands, to generate verbose output. Likewise, the help flag `-h` or `--help,` to print helpful messsages. -A command may additionally take flags specific to it. For example, the `-b ` flag instructs `newt pkg install` to install the pkg from a git `branch.` +A command may additionally take flags specific to it. For example, the `-n ` flag instructs `newt debug` not to start GDB from command line. ```no-highlight - newt pkg install -b <branchname> <eggname> + newt debug <target-name> -n ``` In addition to the [Newt Tool Manual](newt_intro.md) in docs, command-line help is available for each command (and subcommand), through the `-h` or `--help` options. ```no-highlight - $ newt target export --help - Export build targets from the current nest, and print them to - standard output. If the -a (or -export-all) option is specified, - then all targets will be exported. Otherwise, <target-name> - must be specified, and only that target will be exported. - - Usage: - newt target export [flags] - - Examples: - newt target export [-a -export-all] [<target-name>] - newt target export -a > my_exports.txt - newt target export my_target > my_target_export.txt - - Flags: - -a, --export-all=false: If present, export all targets - -h, --help=false: help for export - + newt target --help + Command for manipulating targets + + Usage: + newt target [flags] + newt target [command] + + Available Commands: + config View target system configuration + copy Copy target + create Create a target + delete Delete target + dep View target's dependency graph + revdep View target's reverse-dependency graph + set Set target configuration variable + show View target configuration variables + Global Flags: - -l, --loglevel="WARN": Log level, defaults to WARN. - -q, --quiet=false: Be quiet; only display error output. - -s, --silent=false: Be silent; don't output anything. - -v, --verbose=false: Enable verbose output when executing commands. + -l, --loglevel string Log level (default "WARN") + -o, --outfile string Filename to tee output to + -q, --quiet Be quiet; only display error output + -s, --silent Be silent; don't output anything + -v, --verbose Enable verbose output when executing commands + + Use "newt target [command] --help" for more information about a command. + ``` http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/de74428b/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index 6334cb3..c880035 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -477,12 +477,14 @@ pages: - toc: 'newt/newt_ops.md' - 'newt build': 'newt/command_list/newt_build.md' - 'newt clean': 'newt/command_list/newt_clean.md' + - 'newt complete': 'mewt/command_list/newt_complete.md' - 'newt create-image': 'newt/command_list/newt_create_image.md' - 'newt debug': 'newt/command_list/newt_debug.md' - 'newt help': 'newt/command_list/newt_help.md' - 'newt info': 'newt/command_list/newt_info.md' - 'newt install': 'newt/command_list/newt_install.md' - 'newt load': 'newt/command_list/newt_load.md' + - 'newt mfg': 'newt/command_list/newt_mfg.md' - 'newt new': 'newt/command_list/newt_new.md' - 'newt run': 'newt/command_list/newt_run.md' - 'newt size': 'newt/command_list/newt_size.md'
