Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update getting-started guides for YDK-Py and YDK-Cpp #418

Merged
7 commits merged into from Mar 24, 2017
Merged

Update getting-started guides for YDK-Py and YDK-Cpp #418

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
070edc9
Fix README typos
111pontes Mar 24, 2017
4f93c44
Use dash as consistent separator in bundle name
111pontes Mar 24, 2017
5b40f5f
Update getting-started documentation for YDK-Py
111pontes Mar 24, 2017
1ae9c95
Add minor formatting changes to YDK-Cpp README
111pontes Mar 24, 2017
216d475
Update getting-started documentation for YDK-Cpp
111pontes Mar 24, 2017
3f60eab
Add minor edits to YDK-Py README and documentation
111pontes Mar 24, 2017
f822f12
Merge branch 'master' into tidy-up
Mar 24, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
113 changes: 59 additions & 54 deletions README.md
View file
Open in desktop
@@ -1,38 +1,43 @@
[![License](https://cloud.githubusercontent.com/assets/17089095/19458582/dd626d2c-9481-11e6-8019-8227c5c66a06.png)](https://github.com/CiscoDevNet/ydk-gen/blob/master/LICENSE) [![Build Status](https://travis-ci.org/CiscoDevNet/ydk-gen.svg?branch=master)](https://travis-ci.org/CiscoDevNet/ydk-gen)
[![codecov](https://codecov.io/gh/CiscoDevNet/ydk-gen/branch/master/graph/badge.svg)](https://codecov.io/gh/CiscoDevNet/ydk-gen)

![ydk-logo-128](https://cloud.githubusercontent.com/assets/16885441/24175899/2010f51e-0e56-11e7-8fb7-30a9f70fbb86.png)

YANG Development Kit (Generator)
================================

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [YDK-GEN](#ydk-gen)
- [System requirements](#system-requirements)
- [Installation](#installation)
- [Setting up your environment](#setting-up-your-environment)
- [Clone ydk-gen and install the requirements](#clone-ydk-gen-and-install-the-requirements)
- [Usage](#usage)
- [First step: choose your bundle profile](#first-step-choose-your-bundle-profile)
- [Details](#details)
- [Second step: Generate & install the core](#second-step-generate--install-the-core)
- [Third step: Generate & install your bundle](#third-step-generate--install-your-bundle)
- [Fourth step: Writing your first app](#fourth-step-writing-your-first-app)
- [Documentation](#documentation)
- [Notes](#notes)
- [Python version](#python-version)
- [Directory structure](#directory-structure)
- [Troubleshooting](#troubleshooting)
- [Running Unit Tests](#running-unit-tests)
- [Python](#python)
- [C++](#c)
- [Overview](#overview)
- [System requirements](#system-requirements)
- [Linux](#linux)
- [macOS](#macos)
- [Windows](#windows)
- [Installation](#installation)
- [Setting up your environment](#setting-up-your-environment)
- [Clone ydk-gen and install the requirements](#clone-ydk-gen-and-install-the-requirements)
- [Usage](#usage)
- [First step: choose your bundle profile](#first-step-choose-your-bundle-profile)
- [Details](#details)
- [Second step: Generate & install the core](#second-step-generate--install-the-core)
- [Third step: Generate & install your bundle](#third-step-generate--install-your-bundle)
- [Fourth step: Writing your first app](#fourth-step-writing-your-first-app)
- [Documentation](#documentation)
- [Notes](#notes)
- [Python version](#python-version)
- [Directory structure](#directory-structure)
- [Troubleshooting](#troubleshooting)
- [Running Unit Tests](#running-unit-tests)
- [Python](#python)
- [C++](#c)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

<a href="https://github.com/CiscoDevNet/ydk-gen"><img src="https://cloud.githubusercontent.com/assets/17089095/14834057/2e1fe270-0bb7-11e6-9e94-73dd7d71e87d.png" height="240" width="240" ></a>

# YDK-GEN
# Overview

[![License](https://cloud.githubusercontent.com/assets/17089095/19458582/dd626d2c-9481-11e6-8019-8227c5c66a06.png)](https://github.com/CiscoDevNet/ydk-gen/blob/master/LICENSE) [![Build Status](https://travis-ci.org/CiscoDevNet/ydk-gen.svg?branch=master)](https://travis-ci.org/CiscoDevNet/ydk-gen)
[![codecov](https://codecov.io/gh/CiscoDevNet/ydk-gen/branch/master/graph/badge.svg)](https://codecov.io/gh/CiscoDevNet/ydk-gen)


**ydk-gen** is a developer tool that can generate API bindings to YANG data models for, today, Python and C++, with planned future support for other language bindings.
**ydk-gen** is a developer tool that can generate API's that are modeled in YANG. Currently, it generates language binding for Python and C++ with planned support for other language bindings in the future.

Other tools and libraries are used to deliver `ydk-gen`'s functionality. In particular:

Expand All @@ -44,9 +49,9 @@ Of course, many other libraries are used as an integral part of ydk-gen and its
The output of ydk-gen is either a core package, that defines services and providers, or a module bundle, consisting of APIs based on YANG models. Each module bundle is generated using a bundle profile and the ydk-gen tool. Developers can either use pre-packaged generated bundles (e.g. [ydk-py](http://cs.co/ydk-py)), or they can define their own bundle, consisting of a set of YANG models, using a bundle profile (e.g. [```ietf_0_1_1.json```](profiles/bundles/ietf_0_1_1.json)). This gives a developer the ability to customize the scope of their bundle based on their requirements.


##System requirements
# System requirements

####Linux
## Linux
Ubuntu (Debian-based): The following packages must be present in your system before installing YDK-Py:
```
$ sudo apt-get install python-pip zlib1g-dev python-lxml libxml2-dev libxslt1-dev python-dev libssh-dev libcurl4-openssl-dev libtool-bin libpcre3-dev libpcre++-dev libtool pkg-config python3-dev python3-lxml cmake clang
Expand All @@ -59,19 +64,19 @@ $ sudo yum install python-pip python-devel libxml2-devel libxslt-devel libssh-de
$ sudo ln -fs /usr/bin/cmake3 /usr/bin/cmake
```

####Mac
## macOS
It is recommended to install homebrew (http://brew.sh) and Xcode command line tools on your system before installing YDK-Py:
```
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ xcode-select --install
$ brew install pkg-config cmake libssh xml2 curl pcre
```

####Windows
## Windows
It is recommended to install a python distribution like [PythonXY](https://python-xy.github.io/) on your system before installing YDK-Py

## Installation
### Setting up your environment
# Installation
## Setting up your environment

We recommend that you run ydk-gen under a Python virtual environment (``virtualenv``/``virtualenvwrapper``). To install support in your system, execute

Expand All @@ -92,14 +97,14 @@ At this point, create a new virtual environment
```
$ mkvirtualenv -p python2.7 py2
```
### Clone ydk-gen and install the requirements
## Clone ydk-gen and install the requirements
```
$ git clone https://github.com/CiscoDevNet/ydk-gen.git
$ cd ydk-gen
$ pip install -r requirements.txt
```

## Usage
# Usage

```
$ ./generate.py --help
Expand All @@ -118,13 +123,13 @@ Options:
```
The below steps specify how to use `ydk-gen` to generate the core and a bundle. Pre-generated bundles and core are available for python and C++: [ydk-py](https://github.com/CiscoDevNet/ydk-py) and [ydk-cpp](https://github.com/CiscoDevNet/ydk-cpp).

### First step: choose your bundle profile
## First step: choose your bundle profile

The first step in using ydk-gen is either using one of the already existing [bundle profiles](https://github.com/CiscoDevNet/ydk-gen/tree/master/profiles/bundles) or constructing your own bundle profile, consisting of the YANG models you are interested in:

Construct a bundle profile file, such as [```ietf_0_1_1.json```](profiles/bundles/ietf_0_1_1.json) and specify its dependencies

#### Details
### Details

A sample bundle profile file is described below. The file is in a JSON format. Specify the `name` of your bundle, the `version` of the bundle and the `ydk_version`, which refers to [the version](https://github.com/CiscoDevNet/ydk-gen/releases) of the ydk core package you want to use with this bundle. The `name` of the bundle here is especially important as this will form part of the installation path of the bundle.

Expand Down Expand Up @@ -178,8 +183,8 @@ Only directory examples are shown below.
},
```

### Second step: Generate & install the core
## Second step: Generate & install the core

First, generate the core and install it:

For python:
Expand All @@ -193,13 +198,13 @@ For C++:
$ ./generate.py --cpp --core
$ cd gen-api/cpp/ydk/build && make && sudo make install
```
### Third step: Generate & install your bundle

## Third step: Generate & install your bundle
Then, generate your bundle using a bundle profile and install it:

For python:
```
$ ./generate.py --python --bundle profiles/<name-of-profile>.json
$ ./generate.py --python --bundle profiles/<name-of-profile>.json
$ pip install gen-api/python/<name-of-bundle>-bundle/dist/ydk*.tar.gz
```

Expand All @@ -214,15 +219,15 @@ ydk-models-<name-of-bundle> (0.5.1)

For C++:
```
$ ./generate.py --cpp --bundle profiles/<name-of-profile>.json
$ ./generate.py --cpp --bundle profiles/<name-of-profile>.json
$ cd gen-api/cpp/<name-of-bundle>-bundle/build && make && make install
```

### Fourth step: Writing your first app
## Fourth step: Writing your first app

Now, you can start creating apps based on the models in your bundle. Assuming you generated a python bundle, the models will be available for importing in your app under `ydk.models.<name-of-your-bundle>`. For examples, see [ydk-py-samples](https://github.com/CiscoDevNet/ydk-py-samples#a-hello-world-app) and [C++ samples](sdk/cpp/samples). Also refer to the [documentation for python](http://ydk.cisco.com/py/docs/developer_guide.html) and [for C++](http://ydk.cisco.com/cpp/docs/developer_guide.html).

### Documentation
## Documentation

When generating the YDK documentation for several bundles and the core, it is recommended to generate the bundles without the `--generate-doc` option. After generating all the bundles, the combined documentation for all the bundles and the core can be generated using the `--core --generate-doc` option. For example, the below sequence of commands will generate the documentation for the three python bundles and the python core (for C++, use `--cpp` instead of `--python`).

Expand All @@ -234,16 +239,16 @@ Note that the below process could take a few hours due to the size of the `cisco
./generate.py --python --bundle profiles/bundles/cisco_ios_xr_6_1_1.json
./generate.py --python --core --generate-doc
```
Pre-generated documentation for [ydk-py](http://ydk.cisco.com/py/docs/) and [ydk-cpp](http://ydk.cisco.com/cpp/docs/) are available.
Pre-generated documentation for [ydk-py](http://ydk.cisco.com/py/docs/) and [ydk-cpp](http://ydk.cisco.com/cpp/docs/) are available.

## Notes
# Notes

### Python version
## Python version

- If your environment has both python 2 and python 3 and uses python 2 by default, you may need to use 'python3' and 'pip3' instead of 'python' and 'pip' in the commands mentioned in this document.
- If your environment has both python 2 and python 3 and uses python 2 by default, you may need to use `python3` and `pip3` instead of `python` and `pip` in the commands mentioned in this document.


### Directory structure
## Directory structure

```
README - install and usage notes
Expand All @@ -259,7 +264,7 @@ sdk - sdk core and stubs for python and cpp
test - test code
```

### Troubleshooting
## Troubleshooting
Sometimes, developers using ydk-gen may run across errors when generating a YDK bundle using generate.py with some yang models. If there are issues with the .json profile file being used, such errors will be easily evident. Other times, when the problem is not so evident, it is recommended to try running with the `--verbose|-v` flag, which may reveal syntax problems with the yang models being used. For example,

```
Expand All @@ -272,9 +277,9 @@ cd /path/to/yang/models
pyang *.yang
```

## Running Unit Tests
# Running Unit Tests

### Python
## Python
First, generate and install the [test](profiles/test/ydktest.json) bundle and core package
```
$ ./generate.py --core
Expand All @@ -293,7 +298,7 @@ $ python test/test_sanity_levels.py
$ python test/test_sanity_filters.py
```

### C++
## C++
First, install the [test](profiles/test/ydktest-cpp.json) bundle and core package
```
$ ./generate.py --core --cpp
Expand Down
32 changes: 16 additions & 16 deletions sdk/cpp/README.md
View file
Open in desktop
Expand Up @@ -31,8 +31,8 @@ You can install YDK-Cpp on macOS or Linux. It is not currently supported on Win

Quick Install
-------------
**macOS**
You can install the latest model packages using [homebrew](http://brew.sh). It will manage the dependencies between YDK packages and all other sytem dependencies. First, add the third-party repository (homebrew tap) for YDK:
**macOS**
You can install the latest model packages using [homebrew](http://brew.sh). This utility will manage the dependencies between YDK packages and all other sytem dependencies. First, add the third-party repository (homebrew tap) for YDK:
```
$ brew tap CiscoDevNet/ydk
```
Expand All @@ -42,23 +42,23 @@ You get a fully operational YDK environment by installing the ``cisco-ios-xr`` b
$ brew install ydk-cisco-ios-xr
```

Alternatively, you can perform a partial installation. If you only want to install the ``openconfig`` bundle and its dependencies (``ydk`` and ``ietf`` packages), execute::
Alternatively, you can perform a partial installation. If you only want to install the ``openconfig`` bundle and its dependencies (``ydk`` and ``ietf`` packages), execute:
```
$ brew install ydk-openconfig
```

If you only want to install the ``ietf`` bundle and its dependencies (``ydk`` package), execute::
If you only want to install the ``ietf`` bundle and its dependencies (``ydk`` package), execute:
```
$ brew install ydk-ietf
```

**Linux**
**Linux**
Debian and RPM packages are coming soon. Currently, you have to install it from source (see below).

Installing from source
----------------------
### System Requirements
**Linux**
**Linux**
Ubuntu (Debian-based) - The following packages must be present in your system before installing YDK-Cpp:
```
$ sudo apt-get install libcurl4-openssl-dev libpcre3-dev libssh-dev libxml2-dev libxslt1-dev libtool-bin cmake
Expand All @@ -70,8 +70,8 @@ $ sudo yum install epel-release
$ sudo yum install libxml2-devel libxslt-devel libssh-devel libtool gcc-c++ pcre-devel cmake
```

**Mac**
It is recommended to install homebrew (http://brew.sh) and Xcode command line tools on your system before installing YDK-Cpp
**Mac**
It is recommended to install [homebrew](http://brew.sh) and Xcode command line tools on your system before installing YDK-Cpp:
```
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install curl libssh pcre xml2 cmake
Expand All @@ -86,23 +86,23 @@ $ build$ cmake .. && make
$ build$ sudo make install
```

Once you have installed the ``core`` package, you can install one or more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are captured in the bundle packages used for quick installation. To install the IETF bundle, execute
Once you have installed the ``core`` package, you can install one or more model bundles. Note that some bundles have dependencies on other bundles. Those dependencies are captured in the bundle packages used for quick installation. To install the `ietf` bundle, execute:
```
$ core$ cd ../../ietf
$ ietf$ mkdir build && cd build
$ build$ cmake .. && make
$ build$ sudo make install
```

To install the openconfig bundle, execute
To install the `openconfig` bundle, execute:
```
$ ietf$ cd ../openconfig
$ openconfig$ mkdir build && cd build
$ build$ cmake .. && make
$ build$ sudo make install
```

To install the cisco-ios-xr bundle, execute
To install the `cisco-ios-xr` bundle, execute:
```
$ openconfig$ cd ../cisco-ios-xr
$ cisco-ios-xr$ mkdir build && cd build
Expand All @@ -112,11 +112,11 @@ $ build$ cd ../..
```

Documentation and Support
===============
- Samples can be found under the `core/samples` directory
- API documentation can be found at http://ydk.cisco.com/cpp/docs
- Additional samples can be found at https://github.com/CiscoDevNet/ydk-cpp-samples
- For queries related to usage of the API, please join the YDK community at https://communities.cisco.com/community/developer/ydk
=========================
- Read the [API documentation](http://ydk.cisco.com/cpp/docs) for details on how to use the API and specific models
- Samples can be found under the [samples directory](https://github.com/CiscoDevNet/ydk-cpp/tree/master/core/samples)
- Additional samples can be found in the [YDK-Cpp samples repository](https://github.com/CiscoDevNet/ydk-cpp-samples)
- Join the [YDK community](https://communities.cisco.com/community/developer/ydk) to connect with other users and with the makers of YDK

Release Notes
===============
Expand Down