Adding a New App to the Repository

Important information about Git branch in this document

Although most of the contributions typically target the master branch, the actual branch accepting contributions depends on the Vivado release and needs to be checked on this page.

In this document, the Git branch can be refered as master or <branch> but the exact Git branch name should be used for all the Git commands of this document.

How to Contribute a New App

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

Note: Additional information about Coding Guidelines can be found inside the Tcl Scripting User Guide (UG894)

My First Vivado Tcl App

Let Vivado know where your cloned Tcl repository is located

Before you start Vivado, there is an environment variable that needs to be set 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. A second environment variable XILINX_LOCAL_USER_DATA needs to be set to NO to prevent Vivado from caching some of the catalog files.

export XILINX_TCLAPP_REPO=<WORKING_DIR>/XilinxTclStore
export XILINX_LOCAL_USER_DATA=NO

Some of the Tcl app related commmands in Vivado require a Tcl repo to be present so it is important the environment 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

Note: the Catalog refresh is automatically disabled when XILINX_TCLAPP_REPO points to a local 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 origin master
git merge origin/master

OR

git checkout <branch>
git fetch origin <branch>
git merge origin/<branch>

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 is not important, but the contents of the file must be the same as the one presented 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. You can refer to existing apps inside the Tcl Store repository for additional 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 <MINOR_VERSION> version number needs to be incremented for every change made to the app. Otherwise Vivado will not be able to pull the changes from GitHub. The <MAJOR_VERSION> version number needs to be incremented only when the changes in the app's API are such that it is no more compatible with the previous version. Those requirements are directly driven by the handling of packages by the Tcl language.

Customize the App

Note: The Xilinx Tcl Store requires that the scripts submited to the repository follow some coding guidelines. Refer to UG894 Tcl Scripting for detailed information and examples of the various coding guidelines. The guidelines ensure that the apps are compatible with the Xilinx Tcl Store engine and prevent name collision between the various Tcl scripts inside the repository. The user guide UG894 covers also the command line arguments definition for the Tcl Store.

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:

You must have all procs in namespaces, for example:

# tclapp/mycompany/myapp/myfile.tcl
proc ::tclapp::mycompany::myapp::myproc1 {arg1 {optional1 default_value}} {
    ...
}

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

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 proc was called "myproc", an example usage might be:

  ::tclapp::mycompany::myapp::myproc /home/joe_USER/myfile -owner root

Note: If the proc does not accept any argument, the Argument Usage section should be defined but left empty.

Return Value

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

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.

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

Create the App XML File

The app XML is used by the Tcl Store engine. It includes the list of exported procs along with their short summary as well as other meta data such as the app's display name, revision history and so forth. The app XML is saved under the app directory and is named app.xml

To generate a new app XML file, use the following commands:

Vivado% tclapp::open_app_catalog mycompany::myapp
Vivado% tclapp::add_app_property {display} {...}
Vivado% tclapp::add_app_property {company_display} {...}
Vivado% tclapp::add_app_property {revision_history} {...}
Vivado% tclapp::add_app_property {pkg_require} {...}
Vivado% tclapp::save_app_catalog

The properties for the app are defined as below:

Property Name	Purpose
display	Display name for the app inside the GUI. If not defined then the GUI shows the default app name
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_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

Update the App XML File

If the app.xml already exists, it is not necessary to specify again the app's meta data as they are preserved. A simplified command tclapp::update_app_catalog can be used instead and only the revision history needs to be specified.

Vivado% tclapp::update_app_catalog mycompany::myapp "<revision history>"

Update the Release XML File for GUI testing

To be able to test the app inside the Xilinx Tcl Store GUI, it is necessary to update the release catalog XML file.

Note: The release catalog XML file should never be committed and added to a pull request otherwise. This step is only done for testing the app inside the Vivado GUI. Any pull request that includes the release XML will be rejected.

Vivado% tclapp::update_catalog mycompany::myapp

The release XML can also be updated for multiple apps at once by providing the list of apps:

Vivado% tclapp::update_catalog mycompany1::myapp1 mycompany2::myapp2 ... mycompanyN::myappN

Check the App before you Deploy

Set XILINX_TCLAPP_REPO to point where the local XilinxTclStore is

export XILINX_TCLAPP_REPO=<WORKING_DIR>/XilinxTclStore
export XILINX_LOCAL_USER_DATA=NO

or just the path

export XILINX_TCLAPP_REPO=<WORKING_DIR>
export XILINX_LOCAL_USER_DATA=NO

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.

Testing the app outside of the Tcl Store environment

Require the package that was provided by the app. The package provider script must manually be sourced first.

vivado% source <WORKING_DIR>/tclapp/mycompany/myapp/myapp.tcl
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
...

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

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.

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.

Verify the app information inside the GUI

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

Verify that the app can be installed. Once installed, right click on a proc and verify that the embedded help can be displayed. Uninstall the app.

Add the mandatory copyright/legal document

To be accepted inside the Xilinx Tcl Store, each app must include a copyright/legal document under the following location:

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

Refer to the Open Source BSD 2 license (BSD 2-Clause License ) for further information.

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, <Company Name>
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>

The company name must be on the first line of the document and 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.

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

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

Note: Only files under the app directory must be commited. Do not include any file from the catalog directory

Make sure you commit the correct <branch> to your GitHub repository.

cd <WORKING_DIR>/XilinxTclStore/tclapp/<company>
git checkout <branch>
git status
git add <app>
git status
git commit -m "created myapp for mycompany"
git push origin <branch>

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 under the app:

git add <app>

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 the correct <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 Important information about Git branch in this document

Although most of the contributions typically target the master branch, the actual branch accepting contributions depends on the Vivado release and needs to be checked on this page.

In this document, the Git branch can be refered as master or <branch> but the exact Git branch name should be used for all the Git commands of this document.

How to Contribute a New App

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

Note: Additional information about Coding Guidelines can be found inside the Tcl Scripting User Guide (UG894)

My First Vivado Tcl App

Let Vivado know where your cloned Tcl repository is located

Before you start Vivado, there is an environment variable that needs to be set 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. A second environment variable XILINX_LOCAL_USER_DATA needs to be set to NO to prevent Vivado from caching some of the catalog files.

export XILINX_TCLAPP_REPO=<WORKING_DIR>/XilinxTclStore
export XILINX_LOCAL_USER_DATA=NO

Some of the Tcl app related commmands in Vivado require a Tcl repo to be present so it is important the environment 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

Note: the Catalog refresh is automatically disabled when XILINX_TCLAPP_REPO points to a local 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 origin master
git merge origin/master

OR

git checkout <branch>
git fetch origin <branch>
git merge origin/<branch>

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 is not important, but the contents of the file must be the same as the one presented 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. You can refer to existing apps inside the Tcl Store repository for additional 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 <MINOR_VERSION> version number needs to be incremented for every change made to the app. Otherwise Vivado will not be able to pull the changes from GitHub. The <MAJOR_VERSION> version number needs to be incremented only when the changes in the app's API are such that it is no more compatible with the previous version. Those requirements are directly driven by the handling of packages by the Tcl language.

Customize the App

Note: The Xilinx Tcl Store requires that the scripts submited to the repository follow some coding guidelines. Refer to UG894 Tcl Scripting for detailed information and examples of the various coding guidelines. The guidelines ensure that the apps are compatible with the Xilinx Tcl Store engine and prevent name collision between the various Tcl scripts inside the repository. The user guide UG894 covers also the command line arguments definition for the Tcl Store.

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:

You must have all procs in namespaces, for example:

# tclapp/mycompany/myapp/myfile.tcl
proc ::tclapp::mycompany::myapp::myproc1 {arg1 {optional1 default_value}} {
    ...
}

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

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 proc was called "myproc", an example usage might be:

  ::tclapp::mycompany::myapp::myproc /home/joe_USER/myfile -owner root

Note: If the proc does not accept any argument, the Argument Usage section should be defined but left empty.

Return Value

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

Vivado Package Version

All the scripts within the same app should require the same Vivado package version. Refer to the version requirement for additional information.

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.

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

Create the App XML File

The app XML is used by the Tcl Store engine. It includes the list of exported procs along with their short summary as well as other meta data such as the app's display name, revision history and so forth. The app XML is saved under the app directory and is named app.xml

To generate a new app XML file, use the following commands:

Vivado% tclapp::open_app_catalog mycompany::myapp
Vivado% tclapp::add_app_property {display} {...}
Vivado% tclapp::add_app_property {company_display} {...}
Vivado% tclapp::add_app_property {revision_history} {...}
Vivado% tclapp::add_app_property {pkg_require} {...}
Vivado% tclapp::save_app_catalog

The properties for the app are defined as below:

Property Name	Purpose
display	Display name for the app inside the GUI. If not defined then the GUI shows the default app name
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_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

Update the App XML File

If the app.xml already exists, it is not necessary to specify again the app's meta data as they are preserved. A simplified command tclapp::update_app_catalog can be used instead and only the revision history needs to be specified.

Vivado% tclapp::update_app_catalog mycompany::myapp "<revision history>"

Update the Release XML File for GUI testing

To be able to test the app inside the Xilinx Tcl Store GUI, it is necessary to update the release catalog XML file.

Note: The release catalog XML file should never be committed and added to a pull request otherwise. This step is only done for testing the app inside the Vivado GUI. Any pull request that includes the release XML will be rejected.

Vivado% tclapp::update_catalog mycompany::myapp

The release XML can also be updated for multiple apps at once by providing the list of apps:

Vivado% tclapp::update_catalog mycompany1::myapp1 mycompany2::myapp2 ... mycompanyN::myappN

Check the App before you Deploy

Set XILINX_TCLAPP_REPO to point where the local XilinxTclStore is

export XILINX_TCLAPP_REPO=<WORKING_DIR>/XilinxTclStore
export XILINX_LOCAL_USER_DATA=NO

or just the path

export XILINX_TCLAPP_REPO=<WORKING_DIR>
export XILINX_LOCAL_USER_DATA=NO

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.

Testing the app outside of the Tcl Store environment

Require the package that was provided by the app. The package provider script must manually be sourced first.

vivado% source <WORKING_DIR>/tclapp/mycompany/myapp/myapp.tcl
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
...

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

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.

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.

Verify the app information inside the GUI

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

Verify that the app can be installed. Once installed, right click on a proc and verify that the embedded help can be displayed. Uninstall the app.

Add the mandatory copyright/legal document

To be accepted inside the Xilinx Tcl Store, each app must include a copyright/legal document under the following location:

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

Refer to the Open Source BSD 2 license (BSD 2-Clause License ) for further information.

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, <Company Name>
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>

The company name must be on the first line of the document and 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.

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

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

Note: Only files under the app directory must be commited. Do not include any file from the catalog directory

Make sure you commit the correct <branch> to your GitHub repository.

cd <WORKING_DIR>/XilinxTclStore/tclapp/<company>
git checkout <branch>
git status
git add <app>
git status
git commit -m "created myapp for mycompany"
git push origin <branch>

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 under the app:

git add <app>

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 the correct <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

Adding a New App to the Repository

How to Contribute a New App

My First Vivado Tcl App

Let Vivado know where your cloned Tcl repository is located

Fetch and merge updates to your cloned repository

Create the Directory Structure

Create the Package Provider

Customize the App

Summary

Argument Usage

Return Value

Categories

Running the Linter

Create the Package Index and Tcl Index

Create the App XML File

Update the App XML File

Update the Release XML File for GUI testing

Check the App before you Deploy

Commit Changes

Notify Xilinx by sending a pull request

How to Contribute a New App

My First Vivado Tcl App

Let Vivado know where your cloned Tcl repository is located

Fetch and merge updates to your cloned repository

Create the Directory Structure

Create the Package Provider

Customize the App

Summary

Argument Usage

Return Value

Categories

Vivado Package Version

Running the Linter

Create the Package Index and Tcl Index

Create the App XML File

Update the App XML File

Update the Release XML File for GUI testing

Check the App before you Deploy

Commit Changes

Notify Xilinx by sending a pull request

Clone this wiki locally