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.