Skip to content

Adding a New App to the Repository

Jump to bottom
dpefour edited this page Mar 13, 2014 · 32 revisions

How to Contribute a New App

The expectation is that you have already cloned a local repo and developed code and are ready to contribute.

Some commands described in this document have been added to the upcoming Vivado 2014.1 release and might not work with Vivado 2013.4

My First Vivado Tcl App

Let Vivado know where your cloned Tcl repository is located

Before you start Vivado, there is an environment variable to change the location of the default repository. You need to change this to your local working directory to test the app and generate some needed files. Set XILINX_TCLAPP_REPO to the location of your cloned repository. NOTE - this environment variable will be replaced with a Tcl param in 2014.1, but for now (2013.4) you will need to use an env variable.

export XILINX_TCLAPP_REPO=<WORKING_DIR>/XilinxTclStore

Some of the Tcl app related commmands in Vivado require a Tcl repo to be present so it is important the env variable is set before you start Vivado. Once this is set - do not change it without restarting vivado, we do not currently support multiple repos, and there can be issues if code is not located where it is expected. We will improve this over time.

Note: it is recommended to use an absolute path for the repository

Change the Tcl repository location from within Vivado

The location of the Tcl app repository can also be specified from within Vivado with the following parameter:

set_param tclapp.sharedRepoPath <WORKING_DIR>/XilinxTclStore

Once this parameter has been changed, it is necessary to update or to uninstall/re-install the app to reflect the changes and have the app loaded from the new Tcl repository.

# To update app <APPNAME>, i.e. designutils
tclapp::update <APPNAME>
# or
tclapp::update <COMPANY>::<APPNAME>

# To uninstall/reinstall app <APPNAME>, i.e. designutils
tclapp::uninstall <APPNAME>
tclapp::install <APPNAME>
# or
tclapp::uninstall <COMPANY>::<APPNAME>
tclapp::install <COMPANY>::<APPNAME>

Note: it is recommended to use an absolute path for the repository

Fetch and merge updates to your cloned repository

If you have already cloned the repository, then you may want to fetch and merge the latest updates into your clone.

The lastest and greatest official apps are available in the "master" branch so this is where you want to merge into.

cd XilinxTclStore
git checkout master
git fetch
git merge

Create the Directory Structure

The directory structure should follow <WORKING_DIR>/tclapp/<YOUR_COMPANY>/<YOUR_APP>/...

mkdir -p ./tclapp/mycompany/myapp
cd ./tclapp/mycompany/myapp

More directory and testing structure can be found in tclapp/README.

Create the Package Provider

Every app needs a tcl script that provides packaging information to Vivado. This is called the package provider. The name of the script can be whatever you like, but the contents of the file must be the same as published below. We suggest a .tcl file with the same name as your app, <YOUR_APP>. See one of the existing apps for an example.

vi ./myapp.tcl

Change the version and namespace to match your app. Note that you can also require specific Vivado versions. See other apps in the repository for examples. Create a tcl file with the name of your app in the appropriate app directory and paste the following code in it - again modified appropirately for your app:

# tclapp/mycompany/myapp/myapp.tcl
package require Tcl 8.5

namespace eval ::tclapp::mycompany::myapp {

    # Allow Tcl to find tclIndex
    variable home [file join [pwd] [file dirname [info script]]]
    if {[lsearch -exact $::auto_path $home] == -1} {
    lappend ::auto_path $home
    }

}
package provide ::tclapp::mycompany::myapp 1.0

Note: In the above example, the initial version of the package is 1.0 although it does not have to be. This is up to the app owner to decide on the package version number.

Note: The package version number should have the format <MAJOR_VERSION>.<MINOR_VERSION>. The package version number will need to be incremented for every change made to the app.

Customize the App

Your app scripts will not be able to have this same name, but could be placed inside of this package provider file. If you already have the app created, then copy it into <WORKING_DIR>/tclapp/<YOUR_COMPANY>/<YOUR_APP>/. If you are creating the app from scratch, then:

vi ./myfile.tcl

You need to make sure of a couple things:

  1. You must have all procs in namespaces, for example:
# tclapp/mycompany/myapp/myfile.tcl
proc ::tclapp::mycompany::myapp::myproc1 {arg1 {optional1 default_value}} {
    ...
}
  1. Add the commands that you would like to export to the top of each file. It is important that you are explicit about the commands, in other words, do not use wildcards.
# tclapp/mycompany/myapp/myfile.tcl
namespace eval ::tclapp::mycompany::myapp {
    # Export procs that should be allowed to import into other namespaces
    namespace export myproc1
}
proc ::tclapp::mycompany::myapp::myproc1 {arg1 {optional1 default_value}} {
    ...
}
  1. You must have 4 "meta-comments" which describe your procedure interfaces - inside of the procedures, and each meta-comment must be seperated by new lines (without comments)
# tclapp/mycompany/myapp/myfile.tcl
namespace eval ::tclapp::mycompany::myapp {
    # Export procs that should be allowed to import into other namespaces
    namespace export myproc1
}
proc ::tclapp::mycompany::myapp::myproc1 {arg1 {optional1 default_value}} {

    # Summary: A one line summary of what this proc does

    # Argument Usage:
    # arg1 : A one line summary of this argument which takes a value indicated by <arg>.
    # [optional1 = default_value] : A one line summary of an optional argument that takes a value and which has a default

    # Return Value:
    # TCL_OK is returned with result set to a string

    # Categories: xilinxtclstore, projutils

    ...
}

Each of these meta-comments is interpreted by Vivado at run-time. It is critical that they be present and correct in your app or it may not function correctly. The following is a description of each meta-comment.

Summary

The text following "Summary:" should be a brief, one-line description of your app.

Argument Usage

This is the most complex of the meta-comments. As shown in the above example, there should be one line for each mandatory or optional arg supported by your app. Optional args should be enclosed within []. Args which should be accompanied by a value must be followed by the literal text <, "arg", and >, indicating to the USER where the value should be placed. The summary should explain what are the valid values that a USER might use. You can also specify a default value, which is a value which will be assumed if the USER does not specify the given optional arg. You can also have optional args that do not take any value (these are often referred to as "flags"). For a flag, it's presence on the command line implies a value of true, indicating that some optional action should be take by the app. An exception to this rule is if the name of the flag is prefixed with "no_" (for example, -no_cleanup), in which case a value of false is implied, indicating that the app will not take some action which by default it normally performs.

You can also specify positional args. A positional arg is for which just a value is specified and that has no corresponding flag (e.g. -arg1).

Here is a more concrete example:

        # Argument Usage:
        # file: Name of  file to generate
        # -owner <arg>: USERname of the owner of the file to be generated.
        # [-date <arg> = <todays_date>]: The date to use in yyyy/mm/dd format, will default to today's date if not specified.

This example app has one mandatory positional arg, which is the name of a file it will generate. It also has a mandatory flag -owner, and an optional arg -date, which has a default value. Assuming this app was called "touch", an example usage might be:

  touch /home/joe_USER/myfile -owner root

Use of this command would result in the creation of a file named /home/joe_USER/myfile, owned by root, and with a file creation date of today.

Return Value

Use this meta-comment to specify the possible return values for your app.

Categories

Use this meta-comment to specify which categories in the Vivado help system your app should be listed. "Categories:" should be followed by a comma-separated list. By convention, the first category listed should always be "xilinxtclstore". Any additional categories are up to you as the app developer.

Create the Package Index and Tcl Index

To create neccessary tcl index and package files, invoke Vivado (without creating log and journal files). The instructions below will run commands to create these necessary files in the current directory.

cd <WORKING_DIR>/XilinxTclStore/tclapp/mycompany/myapp
vivado -mode tcl -nolog -nojournal

In Vivado, now issue these Tcl commands:

Vivado% pkg_mkIndex .
Vivado% auto_mkindex .
Vivado% exit

Running the Linter

There is tool in Vivado that checks some basic requirements for the Tcl app store. This is called a "linting" tool.

If you are not already in Vivado:

vivado -mode tcl -nolog -nojournal

There should be a lint_files command available at this point:

Vivado% lint_files [glob <WORKING_DIR>/tclapp/mycompany/myapp/*.tcl]

Correct anything the linter identifies as a problem. Exit Vivado when you are done.

Check the App before you Deploy

  1. Set XILINX_TCLAPP_REPO to point where the local XilinxTclStore is
export XILINX_TCLAPP_REPO=<WORKING_DIR>/XilinxTclStore

or just the path

export XILINX_TCLAPP_REPO=<WORKING_DIR>

Run Vivado

vivado -mode tcl

When the env variable is set, Vivado automatically adds the location of the repository to the auto_load path in Tcl.

  1. Testing the app outside of the Tcl Store environment

Require the package that was provided by the app

vivado% package require ::tclapp::mycompany::myapp

If Vivado fails to retreive the package then there must some error(s) with the Tcl package provider script.

Once the package can be successfully required, the procs can be tested. The namespace where the procs are located is ::tclapp::mycompany::myapp

Optionally import the exported procs

namespace import ::tclapp::mycompany::myapp::*
myproc1
...
  1. Testing the app inside of the Tcl Store environment

Once the code of an app has been tested as a standalone Tcl package, the next step is to check the integration of the app inside the Tcl Store.

Make sure that GIT Access is turned off. Otherwise the Tcl Store will not use the catalog from the local XilinxTclStore repository.

set_param tclapp.enableGitAccess 0

If the local repository has not been specified with the environment variable XILINX_TCLAPP_REPO, the location of the local repo should be set through the following parameter. If the XILINX_TCLAPP_REPO has already been specified before starting Vivado, then this step can be skipped.

set_param tclapp.sharedRepoPath <WORKING_DIR>/XilinxTclStore

The app can be installed from the command line with the following ::tclapp::install command:

tclapp::install <company>::<app>
For example:
tclapp::install mycompany::myapp
Another example:
tclapp::install xilinx::designutils

An equivalent command is available to uninstall the app:

tclapp::uninstall <company>::<app>
For example:
tclapp::uninstall mycompany::myapp
Another example:
tclapp::uninstall xilinx::designutils

To update an app that is already installed, use the tclapp::update command. The command reproduce the Update button in the GUI: the app is first un-installed and then re-installed.

tclapp::update <company>::<app>
For example:
tclapp::update mycompany::myapp
Another example:
tclapp::update xilinx::designutils

Once the app has been installed, the procs that have been exported are available under the namespace <company>::<app>::<proc>

For example:

<company>::<app>::<proc> -help
For example:
xilinx::designutils::write_template -help

Note: if an app is already installed, using tclapp::update or tclapp::install result in both case in the app being un-installed first before being re-installed.

  1. Update the catalog to make the app available to the GUI

To speed up the loading of Vivado, the GUI relies on an XML file to build the list of available apps and the list of procs for each app.

When a new app or a new proc is added, it is necessary to update the catalog XML file to reflect the changes in the GUI.

Note: The commands in this section only work from Vivado 2014.1 and upward. For Vivado 2013.4, the catalog XML file must be manually updated.

Note: future versions of Vivado will provide a more automated way to handle the catalog XML file

The catalog XML for Vivado version <VERSION> is located under:

<WORKING_DIR>/XilinxTclStore/catalog/catalog_<VERSION>.xml

The basic XML structure to be added for an app is:

  <app>
    <revision>1.0</revision>
    <name>MyApp</name>
    <pkg_require>Vivado 2013.1</pkg_require>
    <author>Various Contributors</author>
    <company>xilinx</company>
    <summary>Various Utilities</summary>
    <procs>
      <proc>
        <name>myproc</name>
        <summary>A one line summary of what this proc does</summary>
      </proc>
    </procs>
  </app>

The catalog XML can be altered through some Tcl commands. The following example is an illustration of those commands for the above XML:

# Load the catalog. Vivado automatically picks up the catalog that matches the version of the tool being run
tclapp::load_catalog <WORKING_DIR>/XilinxTclStore
# Add the full path to the app
tclapp::add_app_path <WORKING_DIR>/XilinxTclStore/tclapp/xilinx/MyApp
# Add some properties to the app
tclapp::add_property xilinx::MyApp {name} {MyApp}
tclapp::add_property xilinx::MyApp {display} {A Prettier Name for MyApp}
tclapp::add_property xilinx::MyApp {company} {xilinx}
tclapp::add_property xilinx::MyApp {company_display} {Xilinx, Inc.}
tclapp::add_property xilinx::MyApp {summary} {Various Utilities}
tclapp::add_property xilinx::MyApp {author} {Various Contributors}
tclapp::add_property xilinx::MyApp {pkg_require} {Vivado 2014.1}
tclapp::add_property xilinx::MyApp {revision} 1.0
tclapp::add_property xilinx::MyApp {revision_history} {Initial Version}
# Define the proc(s) exported by the app. One call per proc
tclapp::add_proc xilinx::MyApp myproc
# Add a summary for each proc
tclapp::add_proc_property xilinx::MyApp myproc {summary} {A one line summary of what this proc does}
# Save the catalog to the directory where Vivado was started
tclapp::save_catalog tclstore.xml
# Or save the catalog directly under the correct location
tclapp::save_catalog <WORKING_DIR>/XilinxTclStore/catalog/catalog_<VERSION>.xml
# For example:
tclapp::save_catalog <WORKING_DIR>/XilinxTclStore/catalog/catalog_2014.1.xml

Open the GUI and verify that all the information related to the app are correct.

The properties for the app are defined as below:

Property Name Purpose
name Directory name for the app under XilinxTclStore/<company>
display Display name for the app inside the GUI. If not defined then the GUI shows the default app name
company Directory name for the company under XilinxTclStore
company_display Display name for the company, allow capitalization and spaces
summay Few lines summary to explain the purpose of the app
author Name of the app owner
pkg_require Dependency on Vivado package version
revision Revision number of the app
revision_history Notes of the last changes made to the app

Note: if not specified, the property display is replaced in the GUI by the property name

Note: if not specified, the property company_display is replaced in the GUI by the property company

Note: some properties such as author and company are hidden in the GUI when they are not specified or have an empty content

The screenshot below illustrates the location where the properties are used in the GUI. The company and author properties have not been specified and are therefore not displayed.

Properties in the GUI

  1. Check that the script can be sourced

Any error that would come at the time the script is sourced would prevent the entire app from being loaded.

source <WORKING_DIR>/tclapp/mycompany/myapp/myscript.tcl
  1. Add the mandatory copyright/legal document

For the app to be accepted inside the Xilinx Tcl Store, a copyright/legal document must be added for each app under the following location:

<WORKING_DIR>/XilinxTclStore/tclapp/<company>/<app>/doc/legal.txt

Without this legal document, an app can not be accepted by the Gatekeepers. The content of the legal.txt file must be:

Copyright (c) 2014, Xilinx
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


=================================================================================================
This file must be included in <app>/doc/legal.txt for all accepted contributions to the Xilinx Tcl Store.
All contributors must date and digitally sign once below in order to submit to the Xilinx Tcl Store
<YYYYMMDD Date>::<github id>::<Full Name>
=================================================================================================
<YYYYMMDD Date>::<github id>::<Full Name>

There must be an entry, <YYYYMMDD Date>::<github id>::<Full Name>, per contributor of the app. If all the contributors are from the same company, it is allowed to have a single digital signature for the app owner.

The format <YYYYMMDD Date>::<github id>::<Full Name> is, for example:

20140221::dpefour::David Pefourque

Note: the <github id> is the GitHub User ID, not the company email or Linux identifier.

  1. Add a regression test suite to the app

A regression suite for the app must be created to ensure the healthness of the code and to make sure that the code works as expected.

The location for the test suite is under the directory test of the app:

<WORKING_DIR>/tclapp/mycompany/myapp/test

The test suite must concist of a minimum a test.tcl script that should test the code of the app. Multiple test scripts can be chained inside test.tcl if this is desired.

source <WORKING_DIR>/tclapp/mycompany/myapp/test/test.tcl

For example, if the test for the app concists in 3 different test scripts, the test suite could be structured such as:

<WORKING_DIR>/tclapp/mycompany/myapp/test
<WORKING_DIR>/tclapp/mycompany/myapp/test/test.tcl
<WORKING_DIR>/tclapp/mycompany/myapp/test/test1.tcl
<WORKING_DIR>/tclapp/mycompany/myapp/test/test2.tcl
<WORKING_DIR>/tclapp/mycompany/myapp/test/test3.tcl

With the script test.tcl sourcing test1.tcl, test2.tcl and test3.tcl

  1. Run the regression suite

The contributor is expected to run the regression suite before sending a pull request.

source <WORKING_DIR>/tclapp/mycompany/myapp/test/test.tcl

Note: any temporary file (log, report, ...) created by running the test suite must be removed before commiting the changes.

Commit Changes

Make sure you commit the master branch to your GitHub repository

cd <WORKING_DIR>/XilinxTclStore
git checkout master
git status
git add .
git status
git commit -m "created myapp for mycompany"
git push origin mycompany

Note:

The list of files to be included with the commit is done with the git add command. Either an explicit list of files can be provided:

git add file1 file2 file3
git add file4

Or all the files that have changed:

git add .

Notify Xilinx by sending a pull request

Now that the app and code change have been pushed to your GitHub repository, you can open a browser and log in your GitHub account. From there, send a pull request

Make sure that your master branch is selected before sending the pull request

Note: Be careful as the pull request will include any code change from the Xilinx repository. Make sure that you push into your user GitHub repository only the code you want to be included in the pull request.

Note: It is recommended to only send a pull request for one app at a time. Any pull request that result in involving multiple apps will need to be approved by all the app owners before the pull reqauest could be merge inside Xilinx repo.

Figure 1 - Submitting a Pull Request

Clone this wiki locally