Merge "First real draft of YangIDE user guide."

[docs.git] / manuals / user-guide / src / main / asciidoc / yangide / yangide-user.adoc

== YANG IDE User Guide

=== Overview

The YANG IDE project provides an Eclipse plugin that is used to create,
view, and edit Yang model files.  It currently supports version 1.0 of
the Yang specification.

The YANG IDE project uses components from the OpenDaylight project for
parsing and verifying Yang model files.  The "yangtools" parser in
OpenDaylight is generally used for generating Java code associated
with Yang models.  If you are just using the YANG IDE to view and edit
Yang models, you do not need to know any more about this.

Although the YANG IDE plugin is used in Eclipse, it is not necessary to
be familiar with the Java programming language to use it effectively.

The YANG IDE also uses the Maven build tool, but you do not have to be
a Maven expert to use it, or even know that much about it.  Very
little configuration of Maven files will have to be done by you.  In
fact, about the only thing you will likely ever need to change can be
done entirely in the Eclipse GUI forms, without even seeing the
internal structure of the Maven POM file (Project Object Model).

The YANG IDE plugin provides features that are similar to other
programming language plugins in the Eclipse ecosystem.

For instance, you will find support for the following:

* Immediate "as-you-type" display of syntactic and semantic errors
* Intelligent completion of language tokens, limited to only choices
valid in the current scope and namespace
* Consistent (and customizable) color-coding of syntactic and semantic symbols
* Provides access to remote Yang models by specifying dependency on
Maven artifact containing models (or by manual inclusion in project)
* One-click navigation to referenced symbols in external files
* Mouse hovers display descriptions of referenced components
* Tools for refactoring or renaming components respect namespaces
* Code templates can be entered for common conventions

Forthcoming sections of this manual will step through how to utilize
these features.

=== Creating a Yang Project

After the plugin is installed, the next thing you have to do is create
a Yang Project.  This is done from the "File" menu, selecting "New",
and navigating to the "Yang" section and selecting "YANG Project", and
then clicking "Next" for more items to configure.

Some shortcuts for these steps are the following:

* Typically, the key sequence "Ctrl+n" (press "n" while holding down
one of the "ctrl" keys) is bound to the "new" function
* In the "New" wizard dialog, the initial focus is in the filter
field, where you can enter "yang" to limit the choices to only the
functions provided by the YANG IDE plugin
* On the "New" wizard dialog, instead of clicking the "Next" button
with your mouse, you can press "Alt+n" (you will see a hint for this
with the "N" being underlined)

==== First Yang Project Wizard Page

After the "Next" button is pressed, it goes to the first wizard page
that is specific to creating Yang projects.  you will see a subtitle on
this page of "YANG Tools Configuration".  In almost all cases, you
should be able to click "Next" again on this page to go to the next
wizard page.

However, some information about the fields on this page would be helpful.

You will see the following labeled fields and sections:

===== Yang Files Root Directory

This defaults to "src/main/yang".  Except when creating your first
Yang file, you, you do not even have to know this, as Eclipse presents
the same interface to view your Yang files no matter what you set
this to.

===== Source Code Generators

If you do not know what this is, you do not need to know about it.  The
"yangtools" Yang parser from OpenDaylight uses a "code generator"
component to generate specific kinds of Java classes from the Yang
models.  Again, if you do not need to work with the generated Java
code, you do not need to change this.

===== Create Example YANG File

This is likely the only field you will ever have any reason to change.
If this checkbox is set, when the YANG IDE creates the Yang project,
it will create a sample "acme-system.yang" file which you can view and
edit to demonstrate the features of the tool to yourself.  If you
do not need this file, then either delete it from the project or
uncheck the checkbox to prevent its creation.

When done with the fields on this page, click the "Next" button to go
to the next wizard page.

==== Second Yang Project Wizard Page

This page has a subtitle of "New Maven project".  There are several
fields on this page, but you will only ever have to see and change the
setting of the first field, the "Create a simple project" checkbox.
You should always set this ON to avoid the selection of a Maven
archetype, which is something you do not need to do for creating a
Yang project.

Click "Next" at the bottom of the page to move to the next wizard page.

==== Third Yang Project Wizard Page

This also has a subtitle of "New Maven project", but with different
fields to set.  You will likely only ever set the first two fields,
and completely ignore everything else.

The first field is labeled "Group id" in the "Artifact" section.  It
really does not matter what you set this to, but it does have to be set
to something.  For consistency, you might set this to the name or
nickname of your organization.  Otherwise, there are no constraints on
the value of this field.

The second field is labeled "Artifact id".  The value of this field
will be used as the name of the project you create, so you will have
to think about what you want the project to be called.  Also note that
this name has to be unique in the Eclipse workspace.  You cannot have
two projects with the same name.

After you have set this field, you will notice that the "Next" button is
insensitive, but now the "Finish" button is sensitive.  You can click
"Finish" now (or use the keyboard shortcut of "Alt+f"), and the Yang
IDE will finally create your project.

=== Creating a Yang File

Now that you have created your project, it is time to create your first Yang file.

When you created the Yang project, you might have noticed the other
option next to "YANG Project", which was "YANG File".  That is what
you will select now.  Click "Next" to go to the first wizard page.

==== First Yang File Wizard Page

This wizard page lets you specify where the new file will be located, and its name.

You have to select the particular project you want the file to go
into, and it needs to go into the "src/main/yang" folder (or a
different location if you changed that field when creating the
project).

You then enter the desired name of the file in the "File name".  The
file name should have no spaces or "special characters" in it.  You
can specify a ".yang" extent if you want.  If you do not specify an
extent, the YANG IDE will create it with the ".yang" extent.

Click "Next" to go to the next wizard page.

==== Second Yang File Wizard Page

On this wizard page, you set some metadata about the module that is
used to initialize the contents of the Yang file.

It has the following fields:

===== Module Name

This will default to the "base name" of the file name you created.
For instance, if the file name you created was "network-setup.yang",
this field will default to "network-setup".  You should leave this
value as is.  There is no good reason to define a model with a name
different from the file name.

===== Namespace

This defaults to "urn:opendaylight:xxx", where "xxx" is the "base
name" of the file name you created.  You should put a lot of thought
into designing a namespace naming scheme that is used throughout your
organization.  It is quite common for this namespace value to look like
a "http" URL, but note that that is just a convention, and will not
necessarily imply that there is a web page residing at that HTTP
address.

===== Prefix

This defaults to the "base name" of the file name you created.  It
mostly does not technically matter what you set this to, as long as
it is not empty.  Conventionally, it should be a "nickname" that is
used to refer to the given namespace in an abbreviated form, when
referenced in an "import" statement in another Yang model file.

===== Revision

This has to be a date value in the form of "yyyy-mm-dd", representing
the last modified date of this Yang model.  The value will default to
the current date.

===== Revision Description

This is just human-readable text, which will go into the "description"
field underneath the Yang "revision" field, which will describe what
went into this revision.

When all the fields have the content you want, click the "Finish"
button to set the YANG IDE create the file in the specified location.
It will then present the new file in the editor view for additional
modifications.

=== Accessing Artifacts for Yang Model Imports

You might be working on Yang models that are "abstract" or are
intended to be imported by other Yang models.  You might also, and
more likely, be working on Yang models that import other "abstract"
Yang models.

Assuming you are in that latter more common group, you need to consider
for yourself, and for your organization, how you are going to get
access to those models that you import.

You could use a very simple and primitive approach of somehow
obtaining those models from some source as plain files and just
copying them into the "src/main/yang" folder of your project.  For a
simple demo or a "one-off" very short project, that might be
sufficient.

A more robust and maintainable approach would be to reference
"coordinates" of the artifacts containing Yang models to import.  When
you specify unique coordinates associated with that artifact, the Yang
IDE can retrieve the artifact in the background and make it available
for your "import" statements.

Those "coordinates" that I speak of refer to the Maven concepts of
"group id", "artifact id", and "version".  you may remember "group id"
and "artifact id" from the wizard page for creating a Yang project.
It is the same idea.  If you ever produce Yang model artifacts that
other people are going to import, you will want to think more about what
you set those values to when you created the project.

For example, the OpenDaylight project produces several importable
artifacts that you can specify to get access to common Yang models.

==== Turning on Indexing for Maven Repositories

Before we talk about how to add dependencies to Maven artifacts with
Yang models for import, I need to explain how to make it easier to
find those artifacts.

In the Yang project that you have created, the "pom.xml" file (also
called a "POM file") is the file that Maven uses to specify
dependencies.  We will talk about that in a minute, but first we need to
talk about "repositories".  These are where artifacts are stored.

We are going to have Eclipse show us the "Maven Repositories" view.
In the main menu, select "Window" and then "Show View", and then
"Other".  Like in the "New" dialog, you can enter "maven" in the
filter field to limit the list to views with "maven" in the name.
Click on the "Maven Repositories" entry and click OK.

This will usually create the view in the bottom panel of the window.

The view presents an outline view of four principal elements: 

* Local Repositories
* Global Repositories
* Project Repositories
* Custom Repositories

For this purpose, the only section you care about is "Project
Repositories", being the repositories that are only specified in the
POM for the project.  There should be a "right-pointing arrow" icon on
the line.  Click that to expand the entry.

You should see two entries there:

* opendaylight-release
* opendaylight-snapshot

You will also see internet URLs associated with each of those repositories.

For this purpose, you only care about the first one.  Right-click on
that entry and select "Full Index Enabled".  The first time you do
this on the first project you create, it will spend several minutes
walking the entire tree of artifacts available at that repository and
"indexing" all of those components.  When this is done, searching for
available artifacts in that repository will go very quickly.

=== Adding Dependencies Containing Yang Models

Double-click the "pom.xml" file in your project.  Instead of just
bringing up the view of an XML file (although you can see that if you
like), it presents a GUI form editor with a handful of tabs.

The first tab, "Overview", shows things like the "Group Id", "Artifact
Id", and "Version", which represents the "Maven coordinate" of your
project, which I have mentioned before.

Now click on the "Dependencies" tab.  You will now see two list
components, labeled "Dependencies" and "Dependency Management".  You
only care about the "Dependencies" section.

In the "Dependencies" section, you should see one dependency for an
artifact called "yang-binding".  This artifact is part of
OpenDaylight, but you do not need to know anything about it.

Now click the "Add" button.

This brings up a dialog titled "Select Dependency".  It has three
fields at the top labeled "Group Id", "Artifact Id", and "Version",
with a "Scope" dropdown.  You will never have a need to change the
"Scope" dropdown, so ignore it.  Despite the fact that you will need to
get values into these fields, in general usage, you will never have to
manually enter values into them, but you will see values being inserted
into these fields by the next steps I describe.

Below those fields is a field labeled "Enter groupId, artifactId ...".
This is effectively a "filter field", like on the "New" dialog, but
instead of limiting the list from a short list of choices, the value
you enter there will be matched against all of the artifacts that were
indexed in the "opendaylight-release" repository (and others).  It
will match the string you enter as a substring of any groupId or
artifactId.

For all of the entries that match that substring, it will list an
entry showing the groupId and artifactId, with an expansion arrow.  If
you open it by clicking on the arrow, you will see individual entries
corresponding to each available version of that artifact, along with
some metadata about the artifacts between square brackets, mostly
indicating what "type" of artifact is.

For your purposes, you only ever want to use "bundle" or "jar" artifacts.

Let us consider an example that many people will probably be using.

In the filter field, enter "ietf-yang-types".  Depending on what
versions are available, you should see a small handful of "groupId,
artifactId" entries there.  One of them should be groupId
"org.opendaylight.mdsal.model" and artifactId "ietf-yang-types".
Click on the expansion arrow to open that.

What you will see at this point depends on what versions are
available.  You will likely want to select the newest one (most likely
top of the list) that is also either a "bundle" or "jar" type
artifact.

If you click on that resulting version entry, you should notice at
this point that the "Group Id", "Artifact Id", and "Version" fields at
the top of the dialog are now filled in with the values corresponding
to this artifact and version.

If this is the version that you want, click OK and this artifact will
be added to the dependencies in the POM.

This will now make the Yang models found in that artifact available in
"import" statements in Yang models, not to mention the completion
choices for that "import" statement.