You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/03/18 18:06:10 UTC
[1/3] incubator-mynewt-site git commit: add a file describing a
repository
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/master df9b6fb4d -> 4f897dde0
add a file describing a repository
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/6bc23ba7
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/6bc23ba7
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/6bc23ba7
Branch: refs/heads/master
Commit: 6bc23ba75720c32f9a07b8630e156e15c247de32
Parents: e753d02
Author: Paul Dietrich <pa...@yahoo.com>
Authored: Thu Mar 17 16:28:53 2016 -0700
Committer: Paul Dietrich <pa...@yahoo.com>
Committed: Thu Mar 17 16:28:53 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/add_repos.md | 283 ++++++++++++++++++++++++++++++++++++
mkdocs.yml | 1 +
2 files changed, 284 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6bc23ba7/docs/os/tutorials/add_repos.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/add_repos.md b/docs/os/tutorials/add_repos.md
new file mode 100644
index 0000000..39c7a4e
--- /dev/null
+++ b/docs/os/tutorials/add_repos.md
@@ -0,0 +1,283 @@
+## What is a Repository
+
+A repository is a version-ed mynewt project, which is a
+collection of mynewt packages organized in a specific
+way.
+
+What differentiates a repository from a mynewt project is the presence of a
+`repository.yml` file describing the repository. This will be described
+below.
+
+For the remainder of this document we'll use the term repo as shorthand for a
+mynewt repository.
+
+Repos are useful because they are an organized way for the community
+to share mynewt packages and projects. In fact, the mynewt-core is
+distributed as a repo.
+
+# Additional Repos
+
+Why does mynewt need additional repos?
+
+Repos add functionality
+not included in the mynewt core. New repos might be created for
+several reasons.
+
+* **Expertise**. Individuals or organizations may have expertise that they want
+to share in the form of repos. For example a chip vendor may
+create a repo to hold the mynewt support for their chips.
+* **Non-Core component**. Some components, although very useful to Mynewt users
+are not core to all mynewt users. These are likely candidate to be held in
+different repos.
+* **Software licensing**. Some software has licenses that make them incompatible
+with the ASF (Apache Software Foundation) license policies. These may be
+valuable components to some mynewt users, but cannot be contained in the `apache-mynewt-core`.
+
+## What Repos are in my Project
+
+The list of repos used by your project are contained within the
+`project.yml` file. An example can be seen by creating a new project:
+
+```no-highlight
+$ mkdir ~/dev
+$ cd ~/dev
+$ newt new myproj
+$ cd myproj
+```
+
+View the `project.yml` section and you will see a line describing the repos:
+
+```no-highlight
+project.repositories:
+ - apache-mynewt-core
+```
+
+By default, this newly created project uses a single repo called
+`apache-mynewt-core`.
+
+If you wish to add additional repos, you would add
+additional lines to the `project.repositories` variable like this.
+
+```no-highlight
+project.repositories:
+ - apache-mynewt-core
+ - another_repo_named_x
+```
+
+## Repo Descriptors
+
+In addition to the repo name, the `project.yml` file must also contain
+a repo descriptor for each repository you include that gives `newt`
+information on obtaining the repo.
+
+In the same `myproj` above you will see the following repo descriptor.
+
+```no-highlight
+repository.apache-mynewt-core:
+ type: github
+ vers: 0-latest
+ user: apache
+ repo: incubator-mynewt-core
+```
+
+A repo descriptor starts with `repository.<name>.`. In this example, the
+descriptor specifies the information for the `apache-mynewt-core`.
+
+The fields within the descriptor have the following definitions:
+
+* **type** -- The type of code storage the repo uses. The current version
+of `newt` only supports github. Future versions may support generic git or other
+code storage mechanisms.
+
+* **vers** -- The version of the repo to use for your project. A source
+code repository contains many version of the source. This field is used to
+specify the one to use for this project. See the section on versions below
+for a detailed description of the format of this field.
+
+* **user** -- The username for the repo. On github, this is the name
+after `github.com` in the repo path. Consider the repository
+`https://github.com/apache/incubator-mynewt-core`. It has username `apache`.
+
+* **repo** -- The name of the repo. On github, this is the name after
+the user name described above. Consider the repository
+`https://github.com/apache/incubator-mynewt-core`. It has username
+`incubator-mynewt-core`. This is a path to the source control
+and should not be confused with the name of the repo that you used in the
+`repository.<name>` declaration above. That name is contained elsewhere
+within the repo. See Below.
+
+## Adding Existing Repos to my Project
+
+To add a new repo to your project, you have to complete two steps.
+
+* Edit the `project.yml` file and add a new repo descriptor. The previous
+section includes information on the field required in your repo descriptor.
+
+* Edit the `project/yml` file and add a new line to the `project.repositories`
+variable with the name of the repo you are adding.
+
+An example if a `project.yml` file with two repositories is shown below:
+
+```no-highlight
+project.name: "my_project"
+
+project.repositories:
+ - apache-mynewt-core
+ - mynewt_arduino_zero
+
+# Use github's distribution mechanism for core ASF libraries.
+# This provides mirroring automatically for us.
+#
+repository.apache-mynewt-core:
+ type: github
+ vers: 0-latest
+ user: apache
+ repo: incubator-mynewt-core
+
+# a special repo to hold hardware specific stuff for arduino zero
+repository.mynewt_arduino_zero:
+ type: github
+ vers: 0-latest
+ user: runtimeinc
+ repo: mynewt_arduino_zero
+```
+
+## What Version of the Repo
+
+Mynewt repos are version-ed artifacts. They are stored in source control
+systems like github. The repo descriptor in your `project.yml` file must
+specify the version of the repo you will accept into your project.
+
+For now, we are at the beginnings of mynewt. For testing and evaluation
+please use `0-latest` in the `vers` field in your repo descriptor.
+
+```
+ vers:0-latest
+```
+
+See below for a description of the version system.
+
+## What is in a Repo
+
+A repo is a collection of mynewt packages organized in a specific
+way and stored in one of the supported code storage methods described above.
+
+A repo is a mynewt project, with an additional file `repository.yml`
+which describes the repo for `newt` (and humans browsing them).
+
+There is one key consideration for this `repository.yml` file. The
+`repository.yml` file only lives in the master branch of the git
+repository. `Newt` will always fetch this file from the master branch and then
+use that to resolve the actual branch required depending on the version
+specified in the project. Special care should be taken to ensure that this
+file exists only in the master branch.
+
+Here is the `repository.yml` file from the apache-mynewt-core
+
+```no-highlight
+repo.name: apache-mynewt-core
+repo.versions:
+ "0.7.9": "mynewt_0_8_0_b2_tag"
+ "0-latest": "0.7.9"
+ "0.8-latest": "0.7.9"
+```
+
+it contains the following:
+
+* **repo.name** The external name that is used to include the library in
+your `project.yml` file. This is the name you in include in the `project.repositories` variable when adding this repository to your project.
+* **repo.versions** A description of what versions to give the user depending
+on the settings in their `project.yml` file. See below for a thorough description
+on versioning. Its a flexible mapping between version numbers and git branches.
+
+## Repo Version
+
+The version field argument in your `project.yml` file has the following format:
+
+```no-highlight
+<major_num>.<minor_num>.<revision_num>
+```
+
+or
+
+```no-highlight
+<major_num>.<minor_num>-<stability string>
+```
+
+or
+
+```no-highlight
+<major_num>-<stability string>
+```
+
+The stability string can be one of 3 pre-defined stability values.
+
+1. stable -- A stable release version of the repository
+2. dev -- A development version from the repository
+3. latest -- The latest from the repository
+
+In your `project.yml` file you can specify different combinations of
+the version number and stability value. For example:
+
+* `0-latest` -- The latest version with major number 0
+* `1.2-stable` -- The latest stable version with major and minor number 1.2
+* `1.2-dev` -- The development version from 1.2
+* `1.1.1` -- a specific version 1.1.1
+
+You cannot specify a stability string with a fully number version, e.g.
+
+```no-highlight
+1.2.8-stable
+```
+
+A `repository.yml` file contains information to match this version request
+into a git branch to fetch for your project.
+
+Its up to the repository maintainer to map these to branches of the
+repository. For example, in a fictitious repository, the following are
+defined.
+
+```no-highlight
+repo.versions:
+ "0.8.0": "xxx_branch_0_8_0"
+ "1.0.0": "xxx_branch_1_0_0"
+ "1.0.2": "xxx_branch_1_0_2"
+ "1.1.1": "xxx_branch_1_1_0"
+ "1.1.2": "xxx_branch_1_1_2"
+ "1.2.0": "xxx_branch_1_2_0"
+ "1.2.1": "xxx_branch_1_2_1"
+ "1.2-dev": "1.2.1"
+ "1-dev": "1.2-dev"
+ "1.2-stable": "1.2.0"
+ "0-latest": "0.8.0"
+ "1-latest": "1-dev"
+ ....
+```
+
+When the `project.yml` file asks for `1.2-stable` its resolved to version
+`1.2.0` (perhaps `1.2.1` is not stable yet), which resolves to a specific
+branch `xxx_branch_1_2_0`. This is the branch that `newt` fetches into
+your project.
+
+## How do I find out what Repos are available for Mynewt components
+
+Currently, there is no `newt` command to locate/search mynewt package
+repositories. However, since the `newt` tool supports only github,
+searching github by keyword is a satisfactory option until a search
+tool is created.
+
+When searching github, recall that a mynewt repository must
+have a `repository.yml` file in its root directory. If you don't see
+that file, its not a mynewt repository can cant be included in your
+project via the mynewt tool.
+
+Once you find a repository, the github URL and `repository.yml` file
+should give you all the information to add it to your `project.yml` file.
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6bc23ba7/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index e680744..1b78921 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -26,6 +26,7 @@ pages:
- 'Unit Testing a Package': 'os/tutorials/unit_test.md'
- 'Adding an air-quality sensor': 'os/tutorials/air_quality_sensor.md'
- 'Edit Docs': 'os/tutorials/how_to_edit_docs.md'
+ - 'Additional Repositories': 'os/tutorials/add_repos.md'
- OS User Guide:
- OS Core:
- toc: 'os/core_os/mynewt_os.md'
[2/3] incubator-mynewt-site git commit: Merge branch 'MYNEWT-260' of
https://github.com/paulfdietrich/incubator-mynewt-site
Posted by ad...@apache.org.
Merge branch 'MYNEWT-260' of https://github.com/paulfdietrich/incubator-mynewt-site
This closes #59
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/f705099a
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/f705099a
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/f705099a
Branch: refs/heads/master
Commit: f705099a0fc863136c4e536f2ae7f805eed45fb4
Parents: df9b6fb 6bc23ba
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Mar 18 09:34:52 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Mar 18 09:34:52 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/add_repos.md | 283 ++++++++++++++++++++++++++++++++++++
mkdocs.yml | 1 +
2 files changed, 284 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f705099a/mkdocs.yml
----------------------------------------------------------------------
diff --cc mkdocs.yml
index 5e7faa3,1b78921..6479529
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@@ -25,11 -22,12 +25,12 @@@ pages
- 'Blinky on Olimex': 'os/tutorials/olimex.md'
- 'Blinky on STM32F303': 'os/tutorials/STM32F303.md'
- 'Blinky on nRF52': 'os/tutorials/nRF52.md'
- - 'Blinky on Arduino Zero': 'os/tutorials/arduino_zero.md'
- - 'Unit Testing a Package': 'os/tutorials/unit_test.md'
- - 'Adding an air-quality sensor': 'os/tutorials/air_quality_sensor.md'
+ - 'Write a Test Suite for a Package': 'os/tutorials/unit_test.md'
+ - 'Air-quality Sensor project': 'os/tutorials/air_quality_sensor.md'
- 'Edit Docs': 'os/tutorials/how_to_edit_docs.md'
+ - 'Additional Repositories': 'os/tutorials/add_repos.md'
- OS User Guide:
+ - toc: 'os/os_user_guide.md'
- OS Core:
- toc: 'os/core_os/mynewt_os.md'
- System-level Functions:
[3/3] incubator-mynewt-site git commit: Minor edits to the Additional
REpositories tutorial mainly for formatting. This closes #59.
Posted by ad...@apache.org.
Minor edits to the Additional REpositories tutorial mainly for formatting. This closes #59.
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/4f897dde
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/4f897dde
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/4f897dde
Branch: refs/heads/master
Commit: 4f897dde0a35cebb20f98dcbb0f9b7121a8cd6dc
Parents: f705099
Author: aditihilbert <ad...@runtime.io>
Authored: Fri Mar 18 10:06:02 2016 -0700
Committer: aditihilbert <ad...@runtime.io>
Committed: Fri Mar 18 10:06:02 2016 -0700
----------------------------------------------------------------------
docs/os/tutorials/add_repos.md | 130 ++++++++++++++++++++++--------------
1 file changed, 79 insertions(+), 51 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/4f897dde/docs/os/tutorials/add_repos.md
----------------------------------------------------------------------
diff --git a/docs/os/tutorials/add_repos.md b/docs/os/tutorials/add_repos.md
index 39c7a4e..6213c41 100644
--- a/docs/os/tutorials/add_repos.md
+++ b/docs/os/tutorials/add_repos.md
@@ -1,39 +1,40 @@
-## What is a Repository
+## Additional Repositories
-A repository is a version-ed mynewt project, which is a
-collection of mynewt packages organized in a specific
+### What is a Repository
+
+A repository is a version-ed Mynewt project, which is a
+collection of Mynewt packages organized in a specific
way.
-What differentiates a repository from a mynewt project is the presence of a
+What differentiates a repository from a Mynewt project is the presence of a
`repository.yml` file describing the repository. This will be described
-below.
-
-For the remainder of this document we'll use the term repo as shorthand for a
-mynewt repository.
+below. **Note:** For the remainder of this document we'll use the term repo as shorthand for a
+Mynewt repository.
Repos are useful because they are an organized way for the community
-to share mynewt packages and projects. In fact, the mynewt-core is
+to share Mynewt packages and projects. In fact, the Mynewt-core is
distributed as a repo.
-# Additional Repos
+<br>
-Why does mynewt need additional repos?
+### Why does Mynewt need additional repos?
-Repos add functionality
-not included in the mynewt core. New repos might be created for
+Repos add functionality not included in the Mynewt core. New repos might be created for
several reasons.
* **Expertise**. Individuals or organizations may have expertise that they want
to share in the form of repos. For example a chip vendor may
-create a repo to hold the mynewt support for their chips.
+create a repo to hold the Mynewt support for their chips.
* **Non-Core component**. Some components, although very useful to Mynewt users
-are not core to all mynewt users. These are likely candidate to be held in
+are not core to all Mynewt users. These are likely candidates to be held in
different repos.
-* **Software licensing**. Some software has licenses that make them incompatible
+* **Software licensing**. Some software have licenses that make them incompatible
with the ASF (Apache Software Foundation) license policies. These may be
-valuable components to some mynewt users, but cannot be contained in the `apache-mynewt-core`.
+valuable components to some Mynewt users, but cannot be contained in the `apache-Mynewt-core`.
+
+<br>
-## What Repos are in my Project
+### What Repos are in my Project
The list of repos used by your project are contained within the
`project.yml` file. An example can be seen by creating a new project:
@@ -45,26 +46,32 @@ $ newt new myproj
$ cd myproj
```
+<br>
+
View the `project.yml` section and you will see a line describing the repos:
```no-highlight
project.repositories:
- - apache-mynewt-core
+ - apache-Mynewt-core
```
+<br>
+
By default, this newly created project uses a single repo called
-`apache-mynewt-core`.
+`apache-Mynewt-core`.
If you wish to add additional repos, you would add
additional lines to the `project.repositories` variable like this.
```no-highlight
project.repositories:
- - apache-mynewt-core
+ - apache-Mynewt-core
- another_repo_named_x
```
-## Repo Descriptors
+<br>
+
+### Repo Descriptors
In addition to the repo name, the `project.yml` file must also contain
a repo descriptor for each repository you include that gives `newt`
@@ -73,7 +80,7 @@ information on obtaining the repo.
In the same `myproj` above you will see the following repo descriptor.
```no-highlight
-repository.apache-mynewt-core:
+repository.apache-Mynewt-core:
type: github
vers: 0-latest
user: apache
@@ -81,7 +88,9 @@ repository.apache-mynewt-core:
```
A repo descriptor starts with `repository.<name>.`. In this example, the
-descriptor specifies the information for the `apache-mynewt-core`.
+descriptor specifies the information for the `apache-Mynewt-core`.
+
+<br>
The fields within the descriptor have the following definitions:
@@ -90,7 +99,7 @@ of `newt` only supports github. Future versions may support generic git or othe
code storage mechanisms.
* **vers** -- The version of the repo to use for your project. A source
-code repository contains many version of the source. This field is used to
+code repository contains many versions of the source. This field is used to
specify the one to use for this project. See the section on versions below
for a detailed description of the format of this field.
@@ -99,14 +108,16 @@ after `github.com` in the repo path. Consider the repository
`https://github.com/apache/incubator-mynewt-core`. It has username `apache`.
* **repo** -- The name of the repo. On github, this is the name after
-the user name described above. Consider the repository
+the username described above. Consider the repository
`https://github.com/apache/incubator-mynewt-core`. It has username
`incubator-mynewt-core`. This is a path to the source control
and should not be confused with the name of the repo that you used in the
`repository.<name>` declaration above. That name is contained elsewhere
within the repo. See Below.
-## Adding Existing Repos to my Project
+<br>
+
+### Adding Existing Repos to my Project
To add a new repo to your project, you have to complete two steps.
@@ -122,33 +133,35 @@ An example if a `project.yml` file with two repositories is shown below:
project.name: "my_project"
project.repositories:
- - apache-mynewt-core
- - mynewt_arduino_zero
-
+ - apache-Mynewt-core
+ - Mynewt_arduino_zero
+
# Use github's distribution mechanism for core ASF libraries.
# This provides mirroring automatically for us.
#
-repository.apache-mynewt-core:
+repository.apache-Mynewt-core:
type: github
vers: 0-latest
user: apache
repo: incubator-mynewt-core
-
+
# a special repo to hold hardware specific stuff for arduino zero
-repository.mynewt_arduino_zero:
+repository.Mynewt_arduino_zero:
type: github
vers: 0-latest
user: runtimeinc
- repo: mynewt_arduino_zero
+ repo: Mynewt_arduino_zero
```
-## What Version of the Repo
+<br>
+
+### What Version of the Repo to use
Mynewt repos are version-ed artifacts. They are stored in source control
systems like github. The repo descriptor in your `project.yml` file must
specify the version of the repo you will accept into your project.
-For now, we are at the beginnings of mynewt. For testing and evaluation
+For now, we are at the beginnings of Mynewt. For testing and evaluation
please use `0-latest` in the `vers` field in your repo descriptor.
```
@@ -157,13 +170,15 @@ please use `0-latest` in the `vers` field in your repo descriptor.
See below for a description of the version system.
-## What is in a Repo
+<br>
+
+### What is in a Repo
-A repo is a collection of mynewt packages organized in a specific
+A repo is a collection of Mynewt packages organized in a specific
way and stored in one of the supported code storage methods described above.
-A repo is a mynewt project, with an additional file `repository.yml`
-which describes the repo for `newt` (and humans browsing them).
+A repo is a Mynewt project with an additional file `repository.yml`
+which describes the repo for use by `newt` (and humans browsing them).
There is one key consideration for this `repository.yml` file. The
`repository.yml` file only lives in the master branch of the git
@@ -172,17 +187,19 @@ use that to resolve the actual branch required depending on the version
specified in the project. Special care should be taken to ensure that this
file exists only in the master branch.
-Here is the `repository.yml` file from the apache-mynewt-core
+Here is the `repository.yml` file from the apache-Mynewt-core:
```no-highlight
repo.name: apache-mynewt-core
repo.versions:
- "0.7.9": "mynewt_0_8_0_b2_tag"
+ "0.7.9": "Mynewt_0_8_0_b2_tag"
"0-latest": "0.7.9"
"0.8-latest": "0.7.9"
```
-it contains the following:
+<br>
+
+It contains the following:
* **repo.name** The external name that is used to include the library in
your `project.yml` file. This is the name you in include in the `project.repositories` variable when adding this repository to your project.
@@ -190,7 +207,9 @@ your `project.yml` file. This is the name you in include in the `project.repos
on the settings in their `project.yml` file. See below for a thorough description
on versioning. Its a flexible mapping between version numbers and git branches.
-## Repo Version
+<br>
+
+### Repo Version
The version field argument in your `project.yml` file has the following format:
@@ -210,6 +229,8 @@ or
<major_num>-<stability string>
```
+<br>
+
The stability string can be one of 3 pre-defined stability values.
1. stable -- A stable release version of the repository
@@ -224,17 +245,19 @@ the version number and stability value. For example:
* `1.2-dev` -- The development version from 1.2
* `1.1.1` -- a specific version 1.1.1
-You cannot specify a stability string with a fully number version, e.g.
+You cannot specify a stability string with a fully numbered version, e.g.
```no-highlight
1.2.8-stable
```
+<br>
+
A `repository.yml` file contains information to match this version request
into a git branch to fetch for your project.
Its up to the repository maintainer to map these to branches of the
-repository. For example, in a fictitious repository, the following are
+repository. For example, let's say in a fictitious repository the following are
defined.
```no-highlight
@@ -259,21 +282,26 @@ When the `project.yml` file asks for `1.2-stable` its resolved to version
branch `xxx_branch_1_2_0`. This is the branch that `newt` fetches into
your project.
-## How do I find out what Repos are available for Mynewt components
+<br>
+
+### How to find out what Repos are available for Mynewt components
-Currently, there is no `newt` command to locate/search mynewt package
+Currently, there is no `newt` command to locate/search Mynewt package
repositories. However, since the `newt` tool supports only github,
searching github by keyword is a satisfactory option until a search
tool is created.
-When searching github, recall that a mynewt repository must
+When searching github, recall that a Mynewt repository must
have a `repository.yml` file in its root directory. If you don't see
-that file, its not a mynewt repository can cant be included in your
-project via the mynewt tool.
+that file, it's not a Mynewt repository and can't be included in your
+project via the newt tool.
Once you find a repository, the github URL and `repository.yml` file
should give you all the information to add it to your `project.yml` file.
+<br>
+
+