Skip to content

Adding a New App to the Repository

Jump to bottom
dpefour edited this page Jan 24, 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.

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 the parameter has been changed, it is necessary to uninstall and re-install an app to reflect the changes and have the app loaded from the new Tcl repository.

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

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 ,}} {
    ...
}
  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 ,}} {
    ...
}
  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 ,}} {

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

    # Argument Usage:
    # -arg1 <arg> : A one line summary of this argument which takes a value indicated by <arg>.
    # [-optional1 <arg> = <opt1_default>] : A one line summary of an optional argument that takes a value and which has a default
    # [-optional2] : A one line summary of an optional arg that does not take a value (aka a flag)

    # 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 ~/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. Start testing

Require the package that was provided by the app

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

Optionally import an exported proc

namespace import ::tclapp::mycompany::myapp::*
myproc1
...
  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

Setting up a per repository User Name and Email

cd ~/XilinxTclStore
git config USER.name “johnd”
git config USER.email “johnd@mycompany.com”

Commit Changes

Make sure you commit your <USER> branch.

cd ~/XilinxTclStore
git checkout myorg-johnd
git add .
git status
git commit -m "created myapp for mycompany"
git push origin mycompany
Clone this wiki locally