Repository: incubator-mynewt-site Updated Branches: refs/heads/master 97d68dca3 -> 0f9e111bd
removed legacy terms from newt manual 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/0f9e111b Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/0f9e111b Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/0f9e111b Branch: refs/heads/master Commit: 0f9e111bd111b89ac487d6abd459a679ba93cfa8 Parents: 97d68dc Author: aditihilbert <ad...@runtime.io> Authored: Wed Feb 24 18:30:56 2016 -0800 Committer: aditihilbert <ad...@runtime.io> Committed: Wed Feb 24 18:31:28 2016 -0800 ---------------------------------------------------------------------- docs/newt/command_list/newt_app.md | 52 ++++++ docs/newt/command_list/newt_help.md | 27 +++ docs/newt/command_list/newt_new.md | 39 ++++ docs/newt/command_list/newt_pkg.md | 61 +++++++ docs/newt/command_list/newt_target.md | 127 +++++++++++++ docs/newt/command_list/newt_version.md | 29 +++ docs/newt/newt_intro.md | 3 + docs/newt/newt_linux.md | 106 +++++++++++ docs/newt/newt_mac.md | 130 +++++++++++++ docs/newt/newt_tool_reference.md | 271 ---------------------------- docs/os/core_os/mynewt_os.md | 2 - docs/os/core_os/os_idle_task.md | 0 docs/os/core_os/os_init_idle_task.md | 0 docs/os/get_acclimated/newt_linux.md | 106 ----------- docs/os/get_acclimated/newt_mac.md | 130 ------------- mkdocs.yml | 23 ++- 16 files changed, 591 insertions(+), 515 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/command_list/newt_app.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_app.md b/docs/newt/command_list/newt_app.md new file mode 100644 index 0000000..937944c --- /dev/null +++ b/docs/newt/command_list/newt_app.md @@ -0,0 +1,52 @@ +## <font color="#F2853F" style="font-size:24pt">newt app </font> + + +#### Usage: +```no-highlight + newt app [command][flags] input1 input2... +``` +#### Available commands: +```no-highlight + generate-pkg-list Generate a pkg-list file from the pkgs in the current directory + add-pkg-list Add a remote pkg-list, and put it in the current app + list-pkg-listes List the pkg-listes installed in the current app + show-pkg-list Show an individual pkg-list in the current app +``` + +#### Flags: +```no-highlight + -h, --help=false: help for app +``` +#### Global Flags: +```no-highlight + -h, --help=false: help for newt + -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. +``` +#### Description + +Sub-command | Explanation +-------------| ------------------------ +generate-pkg-list | Takes a snapshot of the pkgs in the current local directory and combines them into a pkg-list by the name of `input1` and with the url of `input2` and generates a standard output of the pkg-list details that can be redirected to a `.yml` pkg-list file. Typically the pkg-list file name is chosen to match the pkg-list name which means the standard output should be directed to a pkg-list file named `input1.yml` +add-pkg-list | Downloads the pkg-list of the name `input1` from the master branch of the github repository `input2` into the current app. A file named `input1.yml` file is added in the `.app/pkg-lists` subdirectory inside the current local app. The `.app/` directory structure is created automatically if it does not exist. +list-pkg-lists | Lists all the pkg-lists present in the current app, including pkg-lists that may have been added from other apps on github. The output shows all the remote pkg-list names and the total pkgshells in each of the pkg-lists. +show-pkg-list | Shows information about the pkg-list that has the name given in the `input1` argument. Output includes the pkg-list name, url, and all the constituent pkgs with their version numbers. + +#### Command-specific flags + +Sub-command | Available flags | Explanation +-------------| ----------------|------------ +add-pkg-list | -b, --branch="<branch-name>" | Fetches the pkg-list file with name `input1` from the specified branch at `input1` url of the github repository. All subsequent pkg installations will be done from that branch. + +#### Examples + +Sub-command | Usage | Explanation +-------------| -----------------------|----------------- +generate-pkg-list | newt app generate-pkg-list mypkg-list https://github.com/apache/incubator-mynewt-larva > mypkg-list.yml| Takes a snapshot of the pkgs in the current app to form a pkg-list named mypkg-list with the url https://github.com/apache/incubator-mynewt-larva. The output is written to a file named `mypkg-list.yml` and describes the properties and contents of the pkg-list (name, url, pkgs). +add-pkg-list | newt app add-pkg-list larva https://github.com/apache/incubator-mynewt-larva | Adds the remote pkg-list named larva at https://github.com/apache/incubator-mynewt-larva to the local app. +list-pkg-lists | newt app list-pkg-lists | Shows all the remote pkg-list description files that been downloaded into the current app. Output includes each list with name and summary of included packages e.g. `Remote package list larva@master (num_pkgs: 44)` +show-pkg-list | newt app show-pkg-list larva | Outputs the details of the pkg-list named larva such as the github url where the remote sits, the constituent pkgs and their versions + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/command_list/newt_help.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_help.md b/docs/newt/command_list/newt_help.md new file mode 100644 index 0000000..8b9f435 --- /dev/null +++ b/docs/newt/command_list/newt_help.md @@ -0,0 +1,27 @@ +## <font color="#F2853F" style="font-size:24pt">newt help </font> + + +#### Usage: +```no-highlight + newt help [input1] +``` +#### Flags: + +```no-highlight + +-h, --help=false: help for newt +-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. +``` + +#### Examples + +Sub-command | Usage | Explanation +-------------| -----------------------|----------------- +help | newt help target | Displays the help text for the newt command 'target' +help | newt help | Displays the help text for newt tool + + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/command_list/newt_new.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_new.md b/docs/newt/command_list/newt_new.md new file mode 100644 index 0000000..13dfbe0 --- /dev/null +++ b/docs/newt/command_list/newt_new.md @@ -0,0 +1,39 @@ +## <font color="#F2853F" style="font-size:24pt">newt new </font> + +Create a new application, specified by <app-name>. If the optional <app-url> +parameter is specified, then download the skeleton of the application from +that URL instead of using the default, and create a new app directory by the name of <app-name> + +#### Usage: +```no-highlight + newt new [flags] <app-name> [, <app-url>] +``` +#### Available commands: +```no-highlight + generate-pkg-list Generate a pkg-list file from the pkgs in the current directory + add-pkg-list Add a remote pkg-list, and put it in the current app + list-pkg-listes List the pkg-listes installed in the current app + show-pkg-list Show an individual pkg-list in the current app +``` + +#### Flags: +```no-highlight + -h, --help=false: help for app +``` +#### Global Flags: +```no-highlight + -h, --help=false: help for newt + -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. +``` + +#### Examples + +Sub-command | Usage | Explanation +-------------| -----------------------|----------------- +create | newt app create test_project | Creates a new app named "test_project " using the default skeleton +create | newt app create myapp <app-url> | Creates a new app named "myapp" using the skeleton at the <app-url> specified + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/command_list/newt_pkg.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_pkg.md b/docs/newt/command_list/newt_pkg.md new file mode 100644 index 0000000..9eccb74 --- /dev/null +++ b/docs/newt/command_list/newt_pkg.md @@ -0,0 +1,61 @@ +## <font color="#F2853F" style="font-size:24pt">newt pkg </font> + +Provides sub-commands to search, display and install packages in your current application or workspace. + +#### Usage: +```no-highlight + newt pkg [command][flag] input1 input2 +``` + +#### Available Commands: +```no-highlight + list List pkgs in the current app + checkdeps Check pkg dependencies + hunt Search for pkg from pkg-lists + show Show the contents of a pkg. + install Install a pkg + remove Remove a pkg +``` +#### Flags: +```no-highlight + -h, --help=false: help for pkg + +#### 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. +``` +#### Description + +Sub-command | Explanation +-------------| ------------------------ +list | List all the pkgs in the current app. The output shows the name, version, path, and any additional attributes of each pkg in the app such as dependencies, capabilities, and linker scripts. The newt command gets the attributes of each pkg from the corresponsing pkg.yml description file. +checkdeps | Resolve all dependencies in the local app. This command goes through all pkgs currently installed, checks their dependencies, and prints any unresolved dependencies between pkgs. +search | Searches for a pkg, specified by `input1`. The local app, along with all remote apps (pkg-lists) are searched. All matched pkgs are shown along with the pkg-list informaton. Installed pkgs are called out as such. The command can be invoked from anywhere in the app. +show | Show the contents of the pkg named `input2` found in the pkg-list named `input1`. The pkg-list name is optional; if only the pkg name is given as the argument it is resolved using all the pkg-lists installed in the current app. If the pkg is present in multiple pkg-lists it will list all of them along with the pkg-list information for each. +install | Install the pkg specified by `input2` from the pkg-list named `input1`. The command downloads the pkg from the github repository using the URL in the pkg-list description file (typically donwloaded as 'input1@<branch-name>.yml' in .app/pkg-lists). It also downloads all the dependencies (constituent pkgs) as decribed in the pkg's description file ('pkg.yml') and installs all of them. The pkg-list name is optional. If only the pkg name is given as the argument, the command looks for the pkg name in all the pkg-lists in the local app and installs accordingly. A pkg is installed by this command only if it has not already been installed. +remove | Remove a pkg named `input2` from pkg-list `input1`, if pkg-list is specified. Otherwise only one input required - that of the name of the pkg to be removed from the local app. + + + + +#### Command-specific flags + +Sub-command | Available flags | Explanation +-------------| ----------------|------------ +install | -b, --branch="<branch-name>" | Installs the pkgs from the branch name or tag of the pkg-list specified + +#### Examples + +Sub-command | Usage | Explanation +-------------| -----------------------|----------------- +list | newt pkg list | CList all of the pkgs in the current app and the details of the pkgs. +checkdeps | newt pkg checkdeps | Checks all the dependencies between pkgs in the app. Lists any unresolved dependencies. +hunt | newt pkg hunt blinky| Hunts for the pkg named 'blinky'. The command can be invoked from anywhere in the app. Results show if the pkg is installed and which pkg-list, if any, has the pkg. +show | newt pkg show larva libs/os | Show the contents of the pkg named 'libs/os' in the pkg-list named larva. The contents are essentially derived from the pkg's 'pkg.yml' file. +install | newt pkg install hw/bsp/stm32f3discovery | Downloads and installs the pkg named "stm32f3discovery" (specified with its full path name inside the remote app) along with all its dependencies from the remote app on github. Since no pkg-list is specified, the URL for the remote app in the pkg-list description file found in the local app (in .app/pkg-lists for the project) is used. +remove | newt pkg remove larva blinky| Removes the pkg named blinky only from the pkg-list named larva +remove | newt pkg remove blinky| Removes the pkg named blinky from the local app + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/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 new file mode 100644 index 0000000..9f31ac6 --- /dev/null +++ b/docs/newt/command_list/newt_target.md @@ -0,0 +1,127 @@ +## <font color="#F2853F" style="font-size:24pt">newt target </font> + +Provides commands to create, build, delete, and query targets. + +#### Usage: + +```no-highlight + newt target [command] input1 [flag1] [flag2] +``` +#### Available Commands: +```no-highlight + set Set target configuration variable + unset Unset target configuration variable + delete Delete target + create Create a target + show View target configuration variables + build Build target + test Test target + size Size of the target + label Add image header to target binary + download Download project to target + debug Open debugger session to target + export Export target + import Import target +``` +#### Flags: +```no-highlight + -h, --help=false: help for target +``` +#### Global Flags: +```no-highlight + -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. +``` +#### Description + +Sub-command | Explanation +-------------| ------------------------ +set | Set attributes of the target. Currently the list of possible attributes are:``` arch, compiler, compiler_def, project, bsp, pkg, identities, capabilities, dependencies, cflags, lflags```. Typically only the first 5 need to be set for a hardware target. For a simulated target, e.g. for software testing purposes, `arch=sim`, `compiler=sim`, and `pkg=<pkg name to be tested>`. You cannot set both the project and pkg for a target. +unset | Unset attributes of the target in its configuration. +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 build <target-name> clean` **before** deleting the target! +create | Creates a target description or build definition by the name `input1`. By default it assigns the sim (simulator) architecture to it which allows you to build new projects and software on your native OS and try it out. +show | Display the configuration defined for the target named `input1`. If no `input1` is specified then show the details for all the targets in the app. +build | Build the source code into an image that can be loaded on the hardware associated with the target named `input1` to do the application enabled by the 'project' associated with that target (via the target definition). It creates 'bin/' and 'bin/<input1>/' subdirectories inside the base directory for the project, compiles and generates binaries and executables, and places them in 'bin/<input1>/. +test | Test a pkg on the target named `input1`. The pkg is either supplied as an argument to the command line invocation of `newt target test` or added as part of the target definition. If only the target is specified as `input1`, then the pkg in the target's definition is automatically chosen to be tested. You currently cannot test an entire project on a hardware target. The test command is envisioned for use if one or two pkgs gets updated and each needs to be tested against a target. Alternatively, a script may be written for a series of tests on several pkgs. +size | Displays the memory used (in bytes) by the component libraries that have been compiled and linked to form the executable for the specified target build (input1). The memory usage of the different components is shown by each memory type available in the bsp (board support package) used in the target e.g. RAM, flash, CCM etc. +label | Appends an image header to the created binary file for the target named `input1`. Version number in the header is set to the value given as `[flag1]`. The manifest.json file in the directory with the binaries (project/<project-name>/bin/<target-name>) reflects the version number. A manifest.json file is created if none exists for the target. +export | Exports the configurations of the specified target `input1`. If -a or -export-all flag is used, then all targets are exported and printed out to standard out. You may redirect the output to a file. +import | Import one or more target configuration from standard input or a file. Each target starts with `@target=<target-name>` followed by the attributes. The list of targets should end with `@endtargets`. +download | Downloads the binary executable `<target-name>.elf.bin` to the board. +debug | Downloads the binary executable `<target-name>.elf.bin` to the board and starts up the openocd/gdb combination session. gdb takes over the terminal. + + +#### Command-specific flags + +Sub-command | Available flags | Explanation +-------------| ----------------|------------ +build | clean | All the binaries and object files for the specified target will be removed. The subdirectory named after the specified target within that project is removed. +build clean | all | All the binaries and object files for all targets are removed, and subdirectories of all targets for the project are removed. However, the entire repository is not emptied since any pkgs or projects that the specified target doesn't reference are not touched. +export | -a, -export-all | Export all targets. `input1` is not necessary when this flag is used. +import | -a, -import-all | Import all targets typed into standard input or redirected from a file. + +#### Examples + + Sub-command | Usage | Explanation +-------------| -----------------------|----------------- +set | newt target set myblinky compiler=arm-none-eabi-m4 | Set the compiler for the 'myblinky' target to the gcc compiler for embedded ARM chips. +unset | newt target unset myblinky compiler | Remove the setting for the compiler for the 'myblinky' target. +delete | newt target delete myblinky | Delete the target description for the target named 'myblinky'. Note that it does not remove any binaries or clean out the directory for this target. +create | newt target create blink_f3disc | Create a new target description by the name 'blink_f3disc'. The architecture is 'sim' by default and can be changed using subcommand 'set' above. +show | newt target show myblinky | Show the target attributes set for 'myblinky' +build | newt target build blink_f3disc | Compile the source code for the target named blink_f3disc and generate binaries that can be loaded into the target hardware. +test | newt target test test_target pkg=libs/os | Tests the pkg named 'libs/os' against the target named 'test_target' +size | newt target size -v boot_olimex | Displays the memory footprint in bytes for all object and linked files for the target named boot_olimex. The -v option shows all the steps of loading and inspecting the different pkgs required for the project on this target as well as the different memory locations available. The memory usage for each component is broken up into the different memory types used. An example output is shown for `newt target size boot_olimex` below. +label | newt target label boot_olimex 2.0.1 | Appends an image header specifying the version number as 2.0.1 to the binary image file for target named boot_olimex. The version number in the manifest.json file for this target is also updated to 2.0.1. +export | newt target export -a > my_exports.txt | Export all build targets from the current app, and redirect output to a file named 'my_exports.txt'. +export | newt target export -export-all | Export all build targets from the current app, and print them to standard output on the screen. +export | newt target export my_target | Export only target named 'my_target' and print it to standard output on the screen. +import | newt target import ex_tgt_1 < exported_targets.txt | Imports the target configuration for 'ex_tgt_1' in 'exported_targets.txt'. +import | newt target import -a < in_targets.txt | Imports all the targets specified in the file named `in_targets.txt`. A sample file is shown after this table. +size | newt target size blink_nordic | Inspects and lists the RAM and Flash memory use by each component (object files and libraries) of the target. +download | newt target -v -lVERBOSE download blinky | Downloads `blinky.elf.bin` to the hardware in verbose mode with logging turned on at VERBOSE level. +debug | newt target debug blinky | Downloads `blinky.elf.bin` to the hardware, opens up a gdb session with `blinky.elf` in the terminal, and halts for further input in gdb. + + +#### Example output for `newt target size boot_olimex`: + +```no-highlight + +$ newt target size boot_olimex +Inspecting target boot_olimex (project = boot) + FLASH CCM RAM + 13 0 3 *fill* + 239 0 0 boot.o + 124 0 0 crt0.o + 84 0 40 crtbegin.o + 4 0 4 crtend.o + 8 0 0 crti.o + 16 0 0 crtn.o + 1396 0 50 libbaselibc.a + 2054 0 1104 libbootutil.a + 84 0 0 libcmsis-core.a + 266 0 4 libfs.a + 80 0 0 libg.a + 1452 0 0 libgcc.a + 940 0 8 libhal.a + 12130 0 538 libnffs.a + 1172 3072 68 libolimex_stm32-e407_devboard.a + 3654 0 645 libos.a + 1504 0 32 libstm32f4xx.a +``` + +#### Example content for `in_targets.txt` file used for importing targets `test3` and `test4`. + +> @target=test3 +project=blinked +arch=sim +compiler_def=debug +compiler=arm-none-eabi-m4 +@target=test4 +project=super_blinky +arch=sim +compiler_def=debug +compiler=arm-none-eabi-m4 +@endtargets http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/command_list/newt_version.md ---------------------------------------------------------------------- diff --git a/docs/newt/command_list/newt_version.md b/docs/newt/command_list/newt_version.md new file mode 100644 index 0000000..a4d0ffc --- /dev/null +++ b/docs/newt/command_list/newt_version.md @@ -0,0 +1,29 @@ +## <font color="#F2853F" style="font-size:24pt">newt version </font> + +Allows you to query the version of newt installed in your application space. + +#### Usage: + +```no-highlight + newt version [flags] +``` + +#### Flags: +```no-highlight + -h, --help=false: help for version +``` +#### Global Flags: +```no-highlight + -l, --loglevel string Log level, defaults to WARN. (default "WARN") + -q, --quiet Be quiet; only display error output. + -s, --silent Be silent; don't output anything. + -v, --verbose Enable verbose output when executing commands. +``` + +#### Examples + +Sub-command | Usage | Explanation +-------------| -----------------------|----------------- +version | newt version | Displays the version of newt tool installed + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/newt_intro.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_intro.md b/docs/newt/newt_intro.md new file mode 100644 index 0000000..695977b --- /dev/null +++ b/docs/newt/newt_intro.md @@ -0,0 +1,3 @@ +## Introduction + +What is newt tool? \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/newt_linux.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_linux.md b/docs/newt/newt_linux.md new file mode 100644 index 0000000..bc4027f --- /dev/null +++ b/docs/newt/newt_linux.md @@ -0,0 +1,106 @@ +## Building newt tool on Linux + + +### Getting your Ubuntu machine Ready + + +#### Installing some prerequisites + +* Install git, libcurl, and the Go language if you do not have them already. +```no-highlight + $ sudo apt-get install git + $ sudo apt-get install libcurl4-gnutls-dev + $ sudo apt-get install golang +``` + +#### Creating local repository + +* The directory structure must be first readied for using Go. Go code must be kept inside a workspace. A workspace is a directory hierarchy with three directories at its root: + + * src contains Go source files organized into packages (one package per directory), + + * pkg contains package objects, and + + * bin contains executable commands. + + The GOPATH environment variable specifies the location of your workspace. First create a 'dev' directory and then a 'go' directory under it. Set the GOPATH environment variable to this directory where you will soon clone the newt tool repository. +```no-highlight + $ cd $HOME + $ mkdir -p dev/go + $ cd dev/go + $ export GOPATH=$PWD +``` + Note that you need to add export statements to ~/.bashrc (or equivalent) to export variables permanently. + +* You are ready to download the newt tool repository. You will use Go to copy the directory (currently the asf incubator directory). Be patient as it may take a minute or two. Check the directories installed. +```no-highlight + $ go get git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt + $ ls + bin pkg src + $ ls src + git-wip-us.apache.org github.com gopkg.in +``` + +* Check that newt is in place. +```no-highlight + $ ls $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt + Godeps README.md coding_style.txt newt.go + LICENSE cli design.txt +``` +#### Building the newt tool + + +* You will use Go to run the newt.go program to build the newt tool. The command used is `go install` which compiles and writes the resulting executable to an output file named `newt`. It installs the results along with its dependencies in $GOPATH/bin. +```no-highlight + $ cd $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt + $ go install + $ ls "$GOPATH"/bin/ + godep incubator-mynewt-newt.git newt +``` +* Try running newt using the compiled binary. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'. + + Note: If you are going to be be modifying the newt tool itself often and wish to compile the program every time you call it, you may want to store the command in a variable in your .bash_profile. So type in `export newt="go run $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt/newt/go"` in your ~/.bashrc (or equivalent) and execute it by calling `$newt` at the prompt instead of `newt`. Here, you use `go run` which runs the compiled binary directly without producing an executable. + +```no-highlight + $ newt version + Newt version: 1.0 + $ newt -h + Newt allows you to create your own embedded project based on the Mynewt + operating system. Newt provides both build and package management in a + single tool, which allows you to compose an embedded workspace, and set + of projects, and then build the necessary artifacts from those projects. + For more information on the Mynewt operating system, please visit + https://www.github.com/mynewt/documentation. + + Please use the newt help command, and specify the name of the command + you want help for, for help on how to use a specific command + + Usage: + newt [flags] + newt [command] + + Examples: + newt + newt help [<command-name>] + For help on <command-name>. If not specified, print this message. + + + Available Commands: + version Display the Newt version number. + target Set and view target information + egg Commands to list and inspect eggs on a nest + nest Commands to manage nests & clutches (remote egg repositories) + help Help about any command + + Flags: + -h, --help=false: help for newt + -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. + + + Use "newt help [command]" for more information about a command. +``` +* Without creating a project repository you can't do a whole lot with the Newt tool. So you'll have to wait till you have downloaded a nest to try out the tool. + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/newt_mac.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_mac.md b/docs/newt/newt_mac.md new file mode 100644 index 0000000..164eaeb --- /dev/null +++ b/docs/newt/newt_mac.md @@ -0,0 +1,130 @@ +## Building newt tool on your Mac + +### Getting your Mac Ready + +If you want to build the newt tool from its source code you need to install +#### Installing Homebrew to ease installs on OS X + +* Do you have Homebrew? If not, open a terminal on your Mac and paste the following at a Terminal prompt. It will ask you for your sudo password. + +```no-highlight + $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +``` + Alternatively, you can just extract (or `git clone`) Homebrew and install it to `/usr/local`. + +#### Installing Go + +* The directory structure must be first readied for using Go. Go code must be kept inside a workspace. A workspace is a directory hierarchy with three directories at its root: + + * src contains Go source files organized into packages (one package per directory), + + * pkg contains package objects, and + + * bin contains executable commands. + + The GOPATH environment variable specifies the location of your workspace. First create a 'dev' directory and then a 'go' directory under it. Set the GOPATH environment variable to this directory where you will soon clone the newt tool repository. + +```no-highlight + $ cd $HOME + $ mkdir -p dev/go + $ cd dev/go + $ export GOPATH=`pwd` +``` + Note that you need to add export statements to ~/.bash_profile to export variables permanently. Don't forget to source the file for the change to go into effect. + +```no-highlight + $ vi ~/.bash_profile + $ source ~/.bash_profile +``` +* Next you will use Homebrew to install Go. The summary message at the end of the installation should indicate that it is installed in the /usr/local/Cellar/go/ directory. You will use the Go command 'install' to compile and install packages (called eggs in the Mynewt world) and dependencies. + +```no-highlight + $ brew install go + ==> + ... + ... + ==> *Summary* + ðº /usr/local/Cellar/go/1.5.1: 5330 files, 273M +``` + Alternatively, you can download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory. + + +#### Creating local repository + +* You are ready to download the newt tool repository. You will use Go to copy the directory (currently the asf incubator directory). Be patient as it may take a minute or two. Check the directories installed. +```no-highlight + $ go get git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt + $ ls + bin pkg src + $ ls src + git-wip-us.apache.org github.com gopkg.in +``` + +If you run into an `unrecognized import path` issue, go to the `~/dev/go/src/git-wip-us.apache.org/repos/asf` directory and create a symbolic link + +```no-highlight + $ ln -s incubator-mynewt-newt.git incubator-mynewt-newt +``` + +* Check that newt.go is in place. +```no-highlight + $ ls $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt + Godeps README.md coding_style.txt newt.go + LICENSE cli design.txt +``` + +#### Building the Newt tool + +* You will use Go to run the newt.go program to build the newt tool. The command used is `go install` which compiles and writes the resulting executable to an output file named `newt`. It installs the results along with its dependencies in $GOPATH/bin. +```no-highlight + $ cd $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt + $ go install + $ ls "$GOPATH"/bin/ + godep incubator-mynewt-newt.git newt +``` +* Try running newt using the compiled binary. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'. + + Note: If you are going to be be modifying the newt tool itself often and wish to compile the program every time you call it, you may want to store the command in a variable in your .bash_profile. So type in `export newt="go run $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt/newt/go"` in your .bash_profile and execute it by calling `$newt` at the prompt instead of `newt`. Here, you use `go run` which runs the compiled binary directly without producing an executable. Don't forget to reload the updated bash profile by typing `source ~/.bash_profile` at the prompt! +```no-highlight + $ newt version + Newt version: 1.0 + $ newt -h + Newt allows you to create your own embedded project based on the Mynewt + operating system. Newt provides both build and package management in a + single tool, which allows you to compose an embedded workspace, and set + of projects, and then build the necessary artifacts from those projects. + For more information on the Mynewt operating system, please visit + https://www.github.com/mynewt/documentation. + + Please use the newt help command, and specify the name of the command + you want help for, for help on how to use a specific command + + Usage: + newt [flags] + newt [command] + + Examples: + newt + newt help [<command-name>] + For help on <command-name>. If not specified, print this message. + + + Available Commands: + version Display the Newt version number. + target Set and view target information + egg Commands to list and inspect eggs on a nest + nest Commands to manage nests & clutches (remote egg repositories) + help Help about any command + + Flags: + -h, --help=false: help for newt + -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. + + + Use "newt help [command]" for more information about a command. +``` +* Without creating a project repository you can't do a whole lot with the Newt tool. So you'll have to wait till you have downloaded a nest to try out the tool. + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/newt/newt_tool_reference.md ---------------------------------------------------------------------- diff --git a/docs/newt/newt_tool_reference.md b/docs/newt/newt_tool_reference.md deleted file mode 100644 index 4ce450f..0000000 --- a/docs/newt/newt_tool_reference.md +++ /dev/null @@ -1,271 +0,0 @@ - -## Command List - -### Available high-level commands - -```no-highlight -version Display the Newt version number -help Help about any command -nest Commands to manage nests & clutches (remote egg repositories) -egg Commands to list and inspect eggs on a nest -target Set and view target information -``` - -### *version* - -#### Usage: - -```no-highlight - newt version [flags] -``` - -Flags: -```no-highlight - -h, --help=false: help for version -``` -Global Flags: -```no-highlight - -h, --help=false: help for newt -``` - -Examples - -Sub-command | Usage | Explanation --------------| -----------------------|----------------- -version | newt version | Displays the version of newt tool installed - - -### *help* - -#### Usage: -```no-highlight - newt help [input1] -``` -Flags: - -```no-highlight - --h, --help=false: help for newt --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. -``` - -Examples - -Sub-command | Usage | Explanation --------------| -----------------------|----------------- -help | newt help target | Displays the help text for the newt command 'target' -help | newt help | Displays the help text for newt tool - - - -### *nest* - -#### Usage: -```no-highlight - newt nest [command][flags] input1 input2... -``` -Available commands: -```no-highlight - create Create a new nest - generate-clutch Generate a clutch file from the eggs in the current directory - add-clutch Add a remote clutch, and put it in the current nest - list-clutches List the clutches installed in the current nest - show-clutch Show an individual clutch in the current nest -``` - -Flags: -```no-highlight - -h, --help=false: help for nest -``` -Global Flags: -```no-highlight - -h, --help=false: help for newt - -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. -``` -Description - -Sub-command | Explanation --------------| ------------------------ -create | Downloads the skeleton of a nest on your local machine from the optional `input2` nest url, if specified, and creates a new nest directory by the name of `input1`. If `input2` is not specified, then a default skeleton from the `tadpole` nest on Mynewt is downloaded. The command lays out a generic directory structure for the nest you are going to build under it and includes some default eggs in it. -generate-clutch | Takes a snapshot of the eggs in the current local directory and combines them into a clutch by the name of `input1` and with the url of `input2` and generates a standard output of the clutch details that can be redirected to a `.yml` clutch file. Typically the clutch file name is chosen to match the clutch name which means the standard output should be directed to a clutch file named `input1.yml` -add-clutch | Downloads the clutch of the name `input1` from the master branch of the github repository `input2` into the current nest. A file named `input1.yml` file is added in the `.nest/clutches` subdirectory inside the current local nest. The `.nest/` directory structure is created automatically if it does not exist. -list-clutches | Lists all the clutches present in the current nest, including clutches that may have been added from other nests on github. The output shows all the remote clutch names and the total eggshells in each of the clutches. -show-clutch | Shows information about the clutch that has the name given in the `input1` argument. Output includes the clutch name, url, and all the constituent eggs with their version numbers. - -Command-specific flags - -Sub-command | Available flags | Explanation --------------| ----------------|------------ -add-clutch | -b, --branch="<branch-name>" | Fetches the clutch file with name `input1` from the specified branch at `input1` url of the github repository. All subsequent egg installations will be done from that branch. - -Examples - -Sub-command | Usage | Explanation --------------| -----------------------|----------------- -create | newt nest create test_project | Creates a new nest named "test_project " using the default skeleton0 -create | newt nest create mynest <nest-url> | Creates a new nest named "mynest" using the skeleton at the <nest-url> specified -generate-clutch | newt nest generate-clutch myclutch https://www.github.com/mynewt/larva > myclutch.yml| Takes a snapshot of the eggs in the current nest to form a clutch named myclutch with the url https://www.github.com/mynewt/larva. The output is written to a file named `myclutch.yml` and describes the properties and contents of the clutch (name, url, eggs). -add-clutch | newt nest add-clutch larva https://www.github.com/mynewt/larva | Adds the remote clutch named larva at www.github.com/mynewt/larva to the local nest. -list-clutches | newt nest list-clutches | Shows all the remote clutch description files that been downloaded into the current nest -show-clutch | newt nest show-clutch larva | Outputs the details of the clutch named larva such as the github url where the remote sits, the constituent eggs and their versions - - -### *egg* - -#### Usage: -```no-highlight - newt egg [command][flag] input1 input2 -``` - -Available Commands: -```no-highlight - list List eggs in the current nest - checkdeps Check egg dependencies - hunt Search for egg from clutches - show Show the contents of an egg. - install Install an egg - remove Remove an egg -``` -Flags: -```no-highlight - -h, --help=false: help for egg - -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. -``` -Description - -Sub-command | Explanation --------------| ------------------------ -list | List all the eggs in the current nest. The output shows the name, version, path, and any additional attributes of each egg in the nest such as dependencies, capabilities, and linker scripts. The newt command gets the attributes of each egg from the corresponsing egg.yml description file. -checkdeps | Resolve all dependencies in the local nest. This command goes through all eggs currently installed, checks their dependencies, and prints any unresolved dependencies between eggs. -hunt | Hunts for an egg, specified by `input1`. The local nest, along with all remote nests (clutches) are searched. All matched eggs are shown along with the clutch informaton. Installed eggs are called out as such. The command can be invoked from anywhere in the nest. -show | Show the contents of the egg named `input2` found in the clutch named `input1`. The clutch name is optional; if only the egg name is given as the argument it is resolved using all the clutches installed in the current nest. If the egg is present in multiple clutches it will list all of them along with the clutch information for each. -install | Install the egg specified by `input2` from the clutch named `input1`. The command downloads the egg from the github repository using the URL in the clutch description file (typically donwloaded as 'input1@<branch-name>.yml' in .nest/clutches). It also downloads all the dependencies (constituent eggs) as decribed in the egg's description file ('egg.yml') and installs all of them. The clutch name is optional. If only the egg name is given as the argument, the command looks for the egg name in all the clutches in the local nest and installs accordingly. An egg is installed by this command only if it has not already been installed. -remove | Remove an egg named `input2` from clutch `input1`, if clutch is specified. Otherwise only one input required - that of the name of the egg to be removed from the local nest. - - - - -Command-specific flags - -Sub-command | Available flags | Explanation --------------| ----------------|------------ -install | -b, --branch="<branch-name>" | Installs the eggs from the branch name or tag of the clutch specified - -Examples - -Sub-command | Usage | Explanation --------------| -----------------------|----------------- -list | newt egg list | CList all of the eggs in the current nest and the details of the eggs. -checkdeps | newt egg checkdeps | Checks all the dependencies between eggs in the nest. Lists any unresolved dependencies. -hunt | newt egg hunt blinky| Hunts for the egg named 'blinky'. The command can be invoked from anywhere in the nest. Results show if the egg is installed and which clutch, if any, has the egg. -show | newt egg show larva libs/os | Show the contents of the egg named 'libs/os' in the clutch named larva. The contents are essentially derived from the egg's 'egg.yml' file. -install | newt egg install hw/bsp/stm32f3discovery | Downloads and installs the egg named "stm32f3discovery" (specified with its full path name inside the remote nest) along with all its dependencies from the remote nest on github. Since no clutch is specified, the URL for the remote nest in the clutch description file found in the local nest (in .nest/clutches for the project) is used. -remove | newt egg remove larva blinky| Removes the egg named blinky only from the clutch named larva -remove | newt egg remove blinky| Removes the egg named blinky from the local nest - - -### *target* - -#### Usage: - -Usage: -```no-highlight - newt target [command] input1 [flag1] [flag2] -``` -Available Commands: -```no-highlight - set Set target configuration variable - unset Unset target configuration variable - delete Delete target - create Create a target - show View target configuration variables - build Build target - test Test target - export Export target - import Import target - download Download image to target - debug Download image to target and start an openocd/gdb session -``` -Flags: -```no-highlight - -h, --help=false: help for target -``` -Global Flags: -```no-highlight - -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. -``` -Description - -Sub-command | Explanation --------------| ------------------------ -set | Set attributes of the target. Currently the list of possible attributes are:``` arch, compiler, compiler_def, project, bsp, egg, identities, capabilities, dependencies, cflags, lflags```. Typically only the first 5 need to be set for a hardware target. For a simulated target, e.g. for software testing purposes, `arch=sim`, `compiler=sim`, and `egg=<egg name to be tested>`. You cannot set both the project and egg for a target. -unset | Unset attributes of the target in its configuration. -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 build <target-name> clean` **before** deleting the target! -create | Creates a target description or build definition by the name `input1`. By default it assigns the sim (simulator) architecture to it which allows you to build new projects and software on your native OS and try it out. -show | Display the configuration defined for the target named `input1`. If no `input1` is specified then show the details for all the targets in the nest. -build | Build the source code into an image that can be loaded on the hardware associated with the target named `input1` to do the application enabled by the 'project' associated with that target (via the target definition). It creates 'bin/' and 'bin/<input1>/' subdirectories inside the base directory for the project, compiles and generates binaries and executables, and places them in 'bin/<input1>/. -test | Test an egg on the target named `input1`. The egg is either supplied as an argument to the command line invocation of `newt target test` or added as part of the target definition. If only the target is specified as `input1`, then the egg in the target's definition is automatically chosen to be tested. You currently cannot test an entire project on a hardware target. The test command is envisioned for use if one or two eggs gets updated and each needs to be tested against a target. Alternatively, a script may be written for a series of tests on several eggs. -export | Exports the configurations of the specified target `input1`. If -a or -export-all flag is used, then all targets are exported and printed out to standard out. You may redirect the output to a file. -import | Import one or more target configuration from standard input or a file. Each target starts with `@target=<target-name>` followed by the attributes. The list of targets should end with `@endtargets`. -size | Outputs the RAM and flash consumption by the components of the specified target `input1`. -download | Downloads the binary executable `<target-name>.elf.bin` to the board. -debug | Downloads the binary executable `<target-name>.elf.bin` to the board and starts up the openocd/gdb combination session. gdb takes over the terminal. - - -Command-specific flags - -Sub-command | Available flags | Explanation --------------| ----------------|------------ -build | clean | All the binaries and object files for the specified target will be removed. The subdirectory named after the specified target within that project is removed. -build clean | all | All the binaries and object files for all targets are removed, and subdirectories of all targets for the project are removed. However, the entire repository is not emptied since any eggs or projects that the specified target doesn't reference are not touched. -export | -a, -export-all | Export all targets. `input1` is not necessary when this flag is used. -import | -a, -import-all | Import all targets typed into standard input or redirected from a file. - -Examples - - Sub-command | Usage | Explanation --------------| -----------------------|----------------- -set | newt target set myblinky compiler=arm-none-eabi-m4 | Set the compiler for the 'myblinky' target to the gcc compiler for embedded ARM chips. -unset | newt target unset myblinky compiler | Remove the setting for the compiler for the 'myblinky' target. -delete | newt target delete myblinky | Delete the target description for the target named 'myblinky'. Note that it does not remove any binaries or clean out the directory for this target. -create | newt target create blink_f3disc | Create a new target description by the name 'blink_f3disc'. The architecture is 'sim' by default and can be changed using subcommand 'set' above. -show | newt target show myblinky | Show the target attributes set for 'myblinky' -build | newt target build blink_f3disc | Compile the source code for the target named blink_f3disc and generate binaries that can be loaded into the target hardware. -test | newt target test test_target egg=libs/os | Tests the egg named 'libs/os' against the target named 'test_target' -export | newt target export -a > my_exports.txt | Export all build targets from the current nest, and redirect output to a file named 'my_exports.txt'. -export | newt target export -export-all | Export all build targets from the current nest, and print them to standard output on the screen. -export | newt target export my_target | Export only target named 'my_target' and print it to standard output on the screen. -import | newt target import ex_tgt_1 < exported_targets.txt | Imports the target configuration for 'ex_tgt_1' in 'exported_targets.txt'. -import | newt target import -a < in_targets.txt | Imports all the targets specified in the file named `in_targets.txt`. A sample file is shown after this table. -size | newt target size blink_nordic | Inspects and lists the RAM and Flash memory use by each component (object files and libraries) of the target. -download | newt target -v -lVERBOSE download blinky | Downloads `blinky.elf.bin` to the hardware in verbose mode with logging turned on at VERBOSE level. -debug | newt target debug blinky | Downloads `blinky.elf.bin` to the hardware, opens up a gdb session with `blinky.elf` in the terminal, and halts for further input in gdb. - -Example content for `in_targets.txt` file used for importing targets `test3` and `test4`. - -> @target=test3 -project=blinked -arch=sim -compiler_def=debug -compiler=arm-none-eabi-m4 -@target=test4 -project=super_blinky -arch=sim -compiler_def=debug -compiler=arm-none-eabi-m4 -@endtargets http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/os/core_os/mynewt_os.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/mynewt_os.md b/docs/os/core_os/mynewt_os.md index 52b7c53..0506f8e 100644 --- a/docs/os/core_os/mynewt_os.md +++ b/docs/os/core_os/mynewt_os.md @@ -36,9 +36,7 @@ Insert introduction here The functions available at the OS level are: -* [os_idle_task](os_idle_task.md) * [os_init](os_init.md) -* [os_init_idle_task](os_init_idle_task.md) * [os_start](os_start.md) * [os_started](os_started.md) http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/os/core_os/os_idle_task.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/os_idle_task.md b/docs/os/core_os/os_idle_task.md deleted file mode 100644 index e69de29..0000000 http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/os/core_os/os_init_idle_task.md ---------------------------------------------------------------------- diff --git a/docs/os/core_os/os_init_idle_task.md b/docs/os/core_os/os_init_idle_task.md deleted file mode 100644 index e69de29..0000000 http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/os/get_acclimated/newt_linux.md ---------------------------------------------------------------------- diff --git a/docs/os/get_acclimated/newt_linux.md b/docs/os/get_acclimated/newt_linux.md deleted file mode 100644 index bc4027f..0000000 --- a/docs/os/get_acclimated/newt_linux.md +++ /dev/null @@ -1,106 +0,0 @@ -## Building newt tool on Linux - - -### Getting your Ubuntu machine Ready - - -#### Installing some prerequisites - -* Install git, libcurl, and the Go language if you do not have them already. -```no-highlight - $ sudo apt-get install git - $ sudo apt-get install libcurl4-gnutls-dev - $ sudo apt-get install golang -``` - -#### Creating local repository - -* The directory structure must be first readied for using Go. Go code must be kept inside a workspace. A workspace is a directory hierarchy with three directories at its root: - - * src contains Go source files organized into packages (one package per directory), - - * pkg contains package objects, and - - * bin contains executable commands. - - The GOPATH environment variable specifies the location of your workspace. First create a 'dev' directory and then a 'go' directory under it. Set the GOPATH environment variable to this directory where you will soon clone the newt tool repository. -```no-highlight - $ cd $HOME - $ mkdir -p dev/go - $ cd dev/go - $ export GOPATH=$PWD -``` - Note that you need to add export statements to ~/.bashrc (or equivalent) to export variables permanently. - -* You are ready to download the newt tool repository. You will use Go to copy the directory (currently the asf incubator directory). Be patient as it may take a minute or two. Check the directories installed. -```no-highlight - $ go get git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt - $ ls - bin pkg src - $ ls src - git-wip-us.apache.org github.com gopkg.in -``` - -* Check that newt is in place. -```no-highlight - $ ls $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt - Godeps README.md coding_style.txt newt.go - LICENSE cli design.txt -``` -#### Building the newt tool - - -* You will use Go to run the newt.go program to build the newt tool. The command used is `go install` which compiles and writes the resulting executable to an output file named `newt`. It installs the results along with its dependencies in $GOPATH/bin. -```no-highlight - $ cd $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt - $ go install - $ ls "$GOPATH"/bin/ - godep incubator-mynewt-newt.git newt -``` -* Try running newt using the compiled binary. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'. - - Note: If you are going to be be modifying the newt tool itself often and wish to compile the program every time you call it, you may want to store the command in a variable in your .bash_profile. So type in `export newt="go run $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt/newt/go"` in your ~/.bashrc (or equivalent) and execute it by calling `$newt` at the prompt instead of `newt`. Here, you use `go run` which runs the compiled binary directly without producing an executable. - -```no-highlight - $ newt version - Newt version: 1.0 - $ newt -h - Newt allows you to create your own embedded project based on the Mynewt - operating system. Newt provides both build and package management in a - single tool, which allows you to compose an embedded workspace, and set - of projects, and then build the necessary artifacts from those projects. - For more information on the Mynewt operating system, please visit - https://www.github.com/mynewt/documentation. - - Please use the newt help command, and specify the name of the command - you want help for, for help on how to use a specific command - - Usage: - newt [flags] - newt [command] - - Examples: - newt - newt help [<command-name>] - For help on <command-name>. If not specified, print this message. - - - Available Commands: - version Display the Newt version number. - target Set and view target information - egg Commands to list and inspect eggs on a nest - nest Commands to manage nests & clutches (remote egg repositories) - help Help about any command - - Flags: - -h, --help=false: help for newt - -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. - - - Use "newt help [command]" for more information about a command. -``` -* Without creating a project repository you can't do a whole lot with the Newt tool. So you'll have to wait till you have downloaded a nest to try out the tool. - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/docs/os/get_acclimated/newt_mac.md ---------------------------------------------------------------------- diff --git a/docs/os/get_acclimated/newt_mac.md b/docs/os/get_acclimated/newt_mac.md deleted file mode 100644 index 164eaeb..0000000 --- a/docs/os/get_acclimated/newt_mac.md +++ /dev/null @@ -1,130 +0,0 @@ -## Building newt tool on your Mac - -### Getting your Mac Ready - -If you want to build the newt tool from its source code you need to install -#### Installing Homebrew to ease installs on OS X - -* Do you have Homebrew? If not, open a terminal on your Mac and paste the following at a Terminal prompt. It will ask you for your sudo password. - -```no-highlight - $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -``` - Alternatively, you can just extract (or `git clone`) Homebrew and install it to `/usr/local`. - -#### Installing Go - -* The directory structure must be first readied for using Go. Go code must be kept inside a workspace. A workspace is a directory hierarchy with three directories at its root: - - * src contains Go source files organized into packages (one package per directory), - - * pkg contains package objects, and - - * bin contains executable commands. - - The GOPATH environment variable specifies the location of your workspace. First create a 'dev' directory and then a 'go' directory under it. Set the GOPATH environment variable to this directory where you will soon clone the newt tool repository. - -```no-highlight - $ cd $HOME - $ mkdir -p dev/go - $ cd dev/go - $ export GOPATH=`pwd` -``` - Note that you need to add export statements to ~/.bash_profile to export variables permanently. Don't forget to source the file for the change to go into effect. - -```no-highlight - $ vi ~/.bash_profile - $ source ~/.bash_profile -``` -* Next you will use Homebrew to install Go. The summary message at the end of the installation should indicate that it is installed in the /usr/local/Cellar/go/ directory. You will use the Go command 'install' to compile and install packages (called eggs in the Mynewt world) and dependencies. - -```no-highlight - $ brew install go - ==> - ... - ... - ==> *Summary* - ðº /usr/local/Cellar/go/1.5.1: 5330 files, 273M -``` - Alternatively, you can download the Go package directly from (https://golang.org/dl/) instead of brewing it. Install it in /usr/local directory. - - -#### Creating local repository - -* You are ready to download the newt tool repository. You will use Go to copy the directory (currently the asf incubator directory). Be patient as it may take a minute or two. Check the directories installed. -```no-highlight - $ go get git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt - $ ls - bin pkg src - $ ls src - git-wip-us.apache.org github.com gopkg.in -``` - -If you run into an `unrecognized import path` issue, go to the `~/dev/go/src/git-wip-us.apache.org/repos/asf` directory and create a symbolic link - -```no-highlight - $ ln -s incubator-mynewt-newt.git incubator-mynewt-newt -``` - -* Check that newt.go is in place. -```no-highlight - $ ls $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt - Godeps README.md coding_style.txt newt.go - LICENSE cli design.txt -``` - -#### Building the Newt tool - -* You will use Go to run the newt.go program to build the newt tool. The command used is `go install` which compiles and writes the resulting executable to an output file named `newt`. It installs the results along with its dependencies in $GOPATH/bin. -```no-highlight - $ cd $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt - $ go install - $ ls "$GOPATH"/bin/ - godep incubator-mynewt-newt.git newt -``` -* Try running newt using the compiled binary. For example, check for the version number by typing 'newt version'. See all the possible commands available to a user of newt by typing 'newt -h'. - - Note: If you are going to be be modifying the newt tool itself often and wish to compile the program every time you call it, you may want to store the command in a variable in your .bash_profile. So type in `export newt="go run $GOPATH/src/git-wip-us.apache.org/repos/asf/incubator-mynewt-newt.git/newt/newt/go"` in your .bash_profile and execute it by calling `$newt` at the prompt instead of `newt`. Here, you use `go run` which runs the compiled binary directly without producing an executable. Don't forget to reload the updated bash profile by typing `source ~/.bash_profile` at the prompt! -```no-highlight - $ newt version - Newt version: 1.0 - $ newt -h - Newt allows you to create your own embedded project based on the Mynewt - operating system. Newt provides both build and package management in a - single tool, which allows you to compose an embedded workspace, and set - of projects, and then build the necessary artifacts from those projects. - For more information on the Mynewt operating system, please visit - https://www.github.com/mynewt/documentation. - - Please use the newt help command, and specify the name of the command - you want help for, for help on how to use a specific command - - Usage: - newt [flags] - newt [command] - - Examples: - newt - newt help [<command-name>] - For help on <command-name>. If not specified, print this message. - - - Available Commands: - version Display the Newt version number. - target Set and view target information - egg Commands to list and inspect eggs on a nest - nest Commands to manage nests & clutches (remote egg repositories) - help Help about any command - - Flags: - -h, --help=false: help for newt - -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. - - - Use "newt help [command]" for more information about a command. -``` -* Without creating a project repository you can't do a whole lot with the Newt tool. So you'll have to wait till you have downloaded a nest to try out the tool. - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/0f9e111b/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index 80b533f..39dd04a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -242,15 +242,26 @@ pages: - 'json_read_object': 'os/modules/json/json_read_object.md' - 'json_target_address': 'os/modules/json/json_target_address.md' - Newt Tool Manual: - - Newt Tool: + - Introduction: 'newt/newt_intro.md' + - Tutorials: + - 'Install newt from source on Mac': 'newt/newt_mac.md' + - 'Install newt from source on Linux': 'newt/newt_linux.md' + - Manual: - 'Command structure': 'newt/newt_ops.md' - - 'Command list': 'newt/newt_tool_reference.md' - - Packaging it: + - 'Command list': + - 'newt app': 'newt/command_list/newt_app.md' + - 'newt help': 'newt/command_list/newt_help.md' + - 'newt new': 'newt/command_list/newt_new.md' + - 'newt pkg': 'newt/command_list/newt_pkg.md' + - 'newt target': 'newt/command_list/newt_target.md' + - 'newt version': 'newt/command_list/newt_version.md' - 'Creating Packages': 'newt/packaging/dist.md' - Newt Manager Manual: - - 'Overview': 'newtmgr/overview.md' - - 'Protocol': 'newtmgr/protocol.md' - - 'Project Slinky': 'newtmgr/project-slinky.md' + - 'Introduction': 'newtmgr/overview.md' + - Tutorials: + - 'Project Slinky': 'newtmgr/project-slinky.md' + - Manual: + - 'Protocol': 'newtmgr/protocol.md' markdown_extensions: - toc:
