docs/getting-started-guide/project-specific-guides/yangide.rst

   1 YANG IDE Installation Guide
   2 ===========================
   3
   4 Overview
   5 --------
   6
   7 The YANG IDE project provides an Eclipse plugin for viewing and editing
   8 Yang model files. When you create a "Yang Project" using the plugin,
   9 it creates a small Maven project with a POM file (pom.xml) that
  10 references the appropriate OpenDaylight dependencies, along with a
  11 sample Yang model file (acme-system.yang).
  12
  13 Pre Requisites for Installing YANG IDE
  14 --------------------------------------
  15
  16 * YANG IDE has the same hardware requirements as the Eclipse IDE, which
  17   is about the same as the hardware requirements for Java 7.
  18 * At least Java 7 is required to run Eclipse (also an obvious
  19   requirement), but Java 8 will be required if you are building an
  20   application using OpenDaylight, and Java 8 is recommended anyway.
  21
  22 Preparing for Installation
  23 --------------------------
  24
  25 As soon as at least Java 7 (Java 8 preferred) and Eclipse are
  26 installed, and Eclipse is running, you can install YANG IDE.
  27
  28 You can find the Oracle Java installer at
  29 http://www.oracle.com/technetwork/java/javase/downloads/index.html .
  30
  31 The Eclipse installer can be found at
  32 http://www.eclipse.org/downloads/ .  You should select the "Eclipse
  33 IDE for Java Developers", and make sure you select the installer for
  34 the correct platform (for instance, 32-bit or 64-bit).
  35
  36
  37 Installing YANG IDE
  38 -------------------
  39
  40 The YANG IDE plugin can be installed by using the public update site URL
  41 provided, which is http://abc.def .
  42
  43 While in Eclipse, select "Help" from the menu bar and select "Install
  44 New Software ...".  On the resulting "Install" dialog, click the
  45 "Add..." button.  In that dialog, enter the update site URL as
  46 specified above and give it a name of "YANG IDE".  Select the provided
  47 plugin and approve the license.
  48
  49 Eclipse will prompt you to restart Eclipse.  Do that.
  50
  51 Installation is complete at this point.
  52
  53 Network Connections
  54 ^^^^^^^^^^^^^^^^^^^
  55
  56 If the installation failed with an indication that it could not reach
  57 the internet, then your work computer may be behind a firewall.
  58 You will need to go to the "Network Connections" section of the Eclipse
  59 preferences (Menubar: "Window"->"Preferences"->"General"->"Network
  60 Connections").
  61
  62 Before you make these changes, you will need to know the host and port
  63 of your outbound proxy server.
  64
  65 On the "Network Connections" page, you should select "Manual" in the
  66 "Active Provider" dropdown, then edit the "HTTP" and "HTTPS" rows in
  67 the table, setting the host and port of the outbound proxy server.
  68
  69 If the proxy server requires authentication, turn on the "Requires
  70 Authentication" checkbox and enter the required userid and password
  71 fields.  If you do not know whether your proxy server requires
  72 authentication, it probably does not.
  73
  74 Verifying your Installation
  75 ---------------------------
  76
  77 This is not really a "usage guide", but following these steps will
  78 verify that the plugin was properly installed.
  79
  80 When installation is complete, you can select "File" from the menu
  81 bar, then "New", then "Other" (you may have a keyboard shortcut for
  82 "Ctrl+n" for this).
  83
  84 In the "New" dialog, you can enter "yang" in the field under the
  85 "Wizards" label, which starts out with the content of "type filter
  86 text".  That will limit the list to the "YANG" folder and the two
  87 choices of "YANG File" and "YANG Project".  Select the "YANG Project"
  88 option and click "Next".
  89
  90 On the "New Yang Project" dialog, you may see a wizard page titled
  91 "Specify YANG Code Generators Parameters".  Do not change anything on
  92 that page and click "Next".
  93
  94 On the next wizard page, with the title "Select project name and
  95 location", check the "Create a simple project" checkbox and click
  96 "Next".
  97
  98 On that dialog, enter anything you want in the "Group Id" field.
  99 Enter a project name (again, whatever you want for now) in the
 100 "Artifact Id" field and click "Finish".  No other fields on the page
 101 need to be changed.
 102
 103 The dialog will now go away and Eclipse will create the project, which
 104 you should see in either the "Package Explorer" or "Project Explorer"
 105 view, on the left side.
 106
 107 Click the arrow just left of the project name to expand the contents
 108 of the project.
 109
 110 In that resulting list, there are only two entries that you will ever
 111 care about.  One is "src/main/yang", which is where you will store the
 112 Yang model files, and the "pom.xml" file, which is where you will enter
 113 dependencies for Yang model files to import.  If you will not be
 114 importing any Yang model files, or you will only be importing other Yang
 115 model files in your own project, then you will never have to do anything
 116 with the "pom.xml" file.
 117
 118 Click the arrow to the left of the "src/main/yang" entry to expand that.
 119
 120 You should see a "acme-system.yang" file, which the plugin created by
 121 default.  Double-click on that entry to open the file in the editor.
 122
 123 Troubleshooting
 124 ^^^^^^^^^^^^^^^
 125
 126 If Eclipse fails to start up initially, then there is something wrong
 127 with either the Java installation or the Eclipse installation.
 128
 129 You can determine whether Java is installed correctly by opening a
 130 shell or command window and entering "java -version" and verifying
 131 whether the output corresponds to the version of Java that you
 132 installed.
 133
 134 If the Java installation seems fine, but Eclipse still fails to start
 135 up, you can ask questions on the #eclipse IRC channel, or post
 136 questions on the "Newcomers" forum at http://www.eclipse.org/forums/ .
 137
 138 If Java and Eclipse seem to be fine, but the YANG IDE is having
 139 problems, ask questions on the "yangide-dev" mailing list.
 140
 141 Post Installation Configuration
 142 -------------------------------
 143
 144 Setting Proxy Used For Maven
 145 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 146
 147 If your work computer sits behind a firewall, you will have had to put
 148 information about your firewall in the "Network Connections" section
 149 of the Eclipse preferences.  That would have allowed you to at least
 150 obtain the plugin and install it into Eclipse.
 151
 152 Much of the functionality of YANG IDE uses Maven internally.  You do
 153 not need to be a Maven expert to use this functionality, but you will
 154 need to add a few more lines of configuration so that Maven can get
 155 through the firewall.  Maven, even when running inside Eclipse, as it
 156 is when you are using YANG IDE, does not use the Eclipse "Network
 157 Connection" settings to reach the internet.  You have to set the proxy
 158 server information in a different place for Maven.
 159
 160 Maven looks for a file at ``$HOME/.m2/settings.xml`` (Linux) or
 161 ``%HOME%\.m2\settings.xml`` (Windows).  If the ``.m2`` folder does not
 162 exist, you will need to create it.  If the "settings.xml" file does not
 163 exist, you should create it with the following contents::
 164
 165     <?xml version="1.0" encoding="UTF-8"?>
 166     <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
 167       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 168       xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
 169       <proxies>
 170         <proxy>
 171           <id>proxy</id>
 172           <active>true</active>
 173           <protocol>http</protocol>
 174           <host>FULLY QUALIFIED NAME OF PROXY HOST</host>
 175           <port>PROXY PORT</port>
 176         </proxy>
 177         <proxy>
 178           <id>proxy2</id>
 179           <active>true</active>
 180           <protocol>https</protocol>
 181           <host>FULLY QUALIFIED NAME OF PROXY HOST</host>
 182           <port>PROXY PORT</port>
 183         </proxy>
 184       </proxies>
 185     </settings>
 186
 187 Replace "FULLY QUALIFIED NAME OF PROXY HOST" and "PROXY PORT" with the
 188 host and port of your proxy server.
 189
 190 If the "settings.xml" file already existed, then you will need to edit
 191 it, inserting the "proxies" element from the above sample at an
 192 appropriate place.
 193
 194 Upgrading From a Previous Release
 195 ---------------------------------
 196
 197 If you already had the "YANG IDE" plugin from "Xored", you will need to
 198 uninstall that plugin before you install this one.
 199
 200 Uninstalling YANG IDE
 201 ---------------------
 202
 203 Uninstalling the YANG IDE plugin is the same as uninstalling any other Eclipse plugin.
 204
 205 Click on the "Help" menu item and select "Installation Details".  That
 206 list will have all the plugins you have installed (or that came with
 207 the distribution).  To uninstall YANG IDE, you will need to select four
 208 entries from that list:
 209
 210 * "m2e connector for YANG"
 211 * "m2e connector for YANG Developer Resources"
 212 * "YANG IDE"
 213 * "YANG IDE Developer Resources"
 214
 215 Use the Control key to select multiple entries in this list.  When all
 216 four entries are selected, click the "Uninstall" button.  The next
 217 dialog shows what you selected and asks you to confirm with the
 218 "Finish" button.
 219
 220 It will then uninstall the plugin and prompt you to restart Eclipse.
 221 When Eclipse restarts, the uninstall process is complete.