git-linux-setup.txt

This is Zoltan's notes on how to set up a Linux machine for accessing and
editing the specification, primarily targeted at the ONF extensibility WG.



If you are behind a proxy, make sure you have the correct settings exported.

> export http_proxy="http://<proxy_host>:<proxy_port>/"
> export https_proxy="http://<proxy_host>:<proxy_port>/"


I. Retrieving the specification from github
============================================


1. github administration
-------------------------
Register a new personal account on github [1]. Request for membership in the
OpenNetworkingFoundation organization [2]. Once you become a member of the
organization you should be able to see the extensibility repository on the
web interface at [3].


[1] https://github.com/
[2] https://github.com/OpenNetworkingFoundation/
[3] https://github.com/OpenNetworkingFoundation/extensibility/



2. install and set-up git
--------------------------
Run the following command to install the required git commands:

> sudo apt-get install git-core

Follow the github description at [1] on how to generate a private ssh key,
and how to register the key on your machine and on github.

If you would like to use a graphical tool for examining the commits added
to the specification, you should also install gitk

> sudo apt-get install gitk


[1] http://help.github.com/linux-set-up-git/



3. retrieve the specification
------------------------------
After these steps you should be able to execute the following command:

> git clone git@github.com:OpenNetworkingFoundation/extensibility.git

This will create a directory called "extensibility", and will copy the entire
repository including all branches. Initially the files and directories in
"extensibility" will reflect the master branch. The specification source can
be found under "of-spec", and the openflow.h file is under "include/openflow".

To make your copy of the specification up-to-date at a later time, execute

> git pull



4. browsing the various branches
---------------------------------
To list the available branches, execute

> git branch -a

To switch over to another branch, execute

> git checkout <branchname>

Note that this should only be used for looking at the branch, but not
for editing and commiting it. You can call the following command to see the
commits added to the current branch

> git log

and the following one to examine a commit, where commit-hash is the long
hexadecimal identifier of a commit

> git diff <commit-hash>

Also if you installed gitk, you can simply run it to examine the commits

> gitk





II. Compiling the specification
================================


1. installing latex
--------------------
The specification is edited in LaTeX, so first you need to install the
texlive package.

> sudo apt-get install texlive --no-install-recommends

The specification require some extra LaTeX package which are part of
most distributions and should be installed.

If your distribution provides those packages, install them and go
directly to step 2.

For example, in Debian, you would have to install those packages :

> sudo apt-get install texlive-latex-extra texlive-doc-base texlive-science texlive-extra-utils texlive-pictures texlive-pstricks latex-xcolor

If your distribution does not provide those packages, the must be
downloaded and installed by hand. For me the following packages were
needed for a fresh texlive installation. If others are also required
for you, you can find the packages at [1]. You can also consult [2] on
installing packages.

> wget http://mirror.ctan.org/macros/latex/contrib/appendix.zip
> wget http://mirror.ctan.org/macros/latex/contrib/bytefield.zip
> wget http://mirror.ctan.org/macros/latex/contrib/multirow.zip
> wget http://mirror.ctan.org/macros/latex/contrib/paralist.zip
> wget http://mirror.ctan.org/obsolete/macros/latex/contrib/subfigure.zip
> wget http://mirror.ctan.org/macros/latex/contrib/xcolor.zip
> wget http://mirror.ctan.org/macros/latex/contrib/xtab.zip

After downloading these zip files, extract each to its own directory, and
for each follow these steps:

   Execute the following command to compile the package. Note: "preprint"
   is a package-bundle, and from that bundle the required package is
   called "fullpage", so in that directory execute "> latex fullpage.ins".
   Also note that "multirow" does not need the following command.

   > latex <packagename>.ins

   This should generate a .sty file, and may generate .cfg files. Next create
   a directory at the following location, and copy the generated .sty and
   .cfg files to the newly created directory. Note: for "preprint" bundle use
   "preprint" as a directory name, and copy fullpage generated files there.

   > sudo mkdir /usr/share/texmf/tex/latex/<packagename>
   > sudo cp *.sty /usr/share/texmf/tex/latex/<packagename>
   > sudo cp *.cfg /usr/share/texmf/tex/latex/<packagename>
   > sudo cp *.def /usr/share/texmf/tex/latex/<packagename>

   It might be possible that the desired location for the packages differ in
   some distributions.

Once this is completed, execute the following command to update the latex
package index:

> sudo mktexlsr


[1] http://www.ctan.org/search/
[2] http://en.wikibooks.org/wiki/LaTeX/Packages/Installing_Extra_Packages



2. installing other packages
-----------------------------
Perl and make is required to build the specification. Those should be
installed on most distributions by default, but if you miss them, execute

> apt-get install make
> apt-get install perl

The texi2pdf and pdftops utilities are also required, so also install the following packages

> sudo apt-get install poppler-utils texinfo



3. compile
-----------
At this point you should be able to compile the specification. Go into the
"of-switch" directory, and execute

> make

As a result "openflow-spec.pdf" should be generated. To view the generated
pdf document, install the xpdf application (if not available)

> sudo apt-get install xpdf

and execute it

> xpdf openflow-spec.pdf

Note: the generated document will reflect the current branch. If you are
interested in another version, select another branch (see I/4.) and rerun
make.




III. Editing the specification
===============================

1. Install a latex editor
--------------------------
There are a number of latex editors available for Linux distributions. As the
current specification relies on custom scripts you'll probably not be able to
use their integrated compile features. Some graphical editors you might like:

TexMaker, a simple editor
> apt-get install texmaker

Kile: a latex editor for KDE
> sudo apt-get install kile

Lyx: a full wysiwyg editor (note that wysiwyg will probably not work for
the specification due to the custom scripts)
- http://www.lyx.org

TeXlipse: an Eclipse plugin for latex editing
- http://texlipse.sourceforge.net/manual/installation.html



2. Creating and working in your local branch
---------------------------------------------
Make sure you that you are viewing the branch you want to base your
work on (see I/4.). To create your local branch, type:

> git checkout -b <newbranchname>

The current convention for branch names is spec/<nickname>/<purpose>.
This command will create a new local branch. From now on you can edit the
contents of the directory locally. Those changes will not be reflected
in the repository yet.

Before doing the first commit, you should set your name and username in your
git environment, so that it gets added to your commits:

> git config --global user.name "<your name>"
> git config --global user.email <your e-mail>

When you are finished with one task on your branch, you can commit those
changes to your local branch. If you created new files, those must be
manually added to the branch by issuing

> git add <filename>

Once you Made sure that the specification can be compiled (see II/3.), you
can commit it by executing

> git commit -am "<short description of the commit>"

You can also look at the status of your local (current) branch by typing

> git status



3. Pushing your work to github
-------------------------------
Once you are complete with your implementation, you can push the branch
- thus creating a new branch on github - with the following command

> git push origin <branchname>:<branchname>



4. Compiling a diff pdf for your work
--------------------------------------
It is possible to compile a pdf file which highlights changes of your
work compared to the original specification.

For this you will have to install latexdiff

> apt-get install latexdiff

Have the source of the original specification available in <origdir>, and
execute the following command

> make diff DIFF_DIR=<origdir>