Merge "Migrate ALTO user docs to rst"

[docs.git] / docs / user-guide / yang-ide-user-guide.rst

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.