Sample Browser

What is the Sample Browser

The sample browser is a tool for delivering Intel oneAPI samples; it is not part of this GitHub repo. The sample browser uses attributes from the sample's sample.json file understand how to display and name the samples and how to create oneAPI samples on your system. A sample.json file is included in the root of each sample.

There are currently (May 2021) four "sample browsers":

Eclipse samples browser plugin (Linux dev systems)
"Visual Studio" samples browser extension (Windows dev systems)
"Visual Studio Code" samples browser extension (all supported OSes)
oneapi-cli samples browser for command-line
- Linux
- Windows

Other sample browsers may be added as part of future oneAPI releases.

Use of the `samples.json` File by the Sample Browsers

This section describes how each sample browser interprets the sample.json file included with each sample. It is written primarily for use by the sample browser implementors, but it can also be used by sample authors to better understand how the behavior of the sample browsers impacts their choices when writing a sample.json file. For more information on the samples.json see the sample.json Specification

A Typical `sample.json` File

See the examples provided in the sample.json Specification wiki page.

`sample.json` Attribute Details

{
  "name": "<sample-name>",
  "description": "<sample-description>",
  "categories": ["<tab-name>/<component-name>/<sample-type>/<etc>", "..."],
  "toolchain": ["<compiler-list>", "..."],
  "languages": [{"<project-language>":{}}],
  "dependencies": ["<dependency-list>", "..."],
  "targetDevice": ["<target-device-list>", "..."],
  "sampleReadmeUri": "https://software.intel.com/my-custom-readme.html",
  "os": ["<supported-dev-host-list>", "..."],
  "altindex": true,
  "builder": ["<builder-id>", "..."],
  "guid": "01234567-89AB-CDEF-0123-456789ABCDEF"
}

NOTE: Per the JSON specification: "A [JSON] array is an ordered sequence of zero or more values." Meaning that you can rely on the order of array elements, as seen by the various sample browsers, to be consistent with their presentation in the sample.json file. See the Introduction in rfc-7159 for reference. The order of all other JSON elements is not guaranteed, only array elements.

The ordered sequence characteristic of JSON arrays is taken advantage of by several sample.json attributes as a way of specifying a priority order. Only JSON array elements include this guaranteed ordered sequence property. The order of elements within an object are not guaranteed.

`"name"`

This attribute is recognized by all sample browsers.

A string that contains the name of the sample for presentation by the sample browser. There is no prescribed limit to the length of the string, but the sample browser should clip presentation of any "name" string that is longer than 50 characters.

IF (length of name > 50 characters)
    truncate displayed string to 50 characters in length ;

`"description"`

This attribute is recognized by all sample browsers.

A string that contains a short description of the sample, for presentation by the sample browser. There is no prescribed limit to the length of the string, but the sample browser should clip presentation of any "description" string that is longer than 250 characters. Longer than this is likely to not display well in the sample browser dialog which may also be displaying dependencies and other informational bits that are relevant to the sample.

IF (length of description > 250 characters)
    truncate displayed string to 250 characters in length ;

`"categories"`

This attribute is recognized by all sample browsers.

Contains an array of "category string" elements, where each category string follows this basic format:

<tab-name>/<component-name>/<sample-type>/<etc>

Defining more than one category string is unusual, most samples only need to define a single category string element. That is, for the typical sample there is only one string element defined in the "categories" array.

NOTE: Consult with the UX/DX team and samples working group for guidelines regarding the allowed "categories" names and strings.

A category string defines the tree hierarchy to be displayed by the sample browser, for presentation of the sample within a tree of samples (ala a directory of folders that contain an assortment of samples). The category string does not include the name of the sample, only the tree path in which the sample should be located. The precise meaning of each level in the tree is subject to change, the template names shown above are for illustration only.

Providing multiple category strings in the "categories" array signals that the sample is requesting to appear in more than one location within the overall sample tree presented by the sample browser. That is, the sample is requesting that it appear under more than one category; this is not typical.

The '/' characters within a category string define the tree hierarchy, they separate nodes in the tree. A '/' character that starts or ends a category string is considered to be an excess character. Duplicate '/' characters are also considered to be excess. Excess characters are expected to be ignored by the sample browser. This means that it is impossible to include the '/' character as part of a sample category name.

If the UX/DX team prescribes specific meaning to nodes in the category tree hierarchy (e.g., <tab-name> must always be named "Toolkits"), the sample browser will validate those specific nodes. If a category string does not meet the naming requirements defined by the UX/DX team the sample browser will rename the category string to "Unknown" for that sample that is using incorrect category names. This practice will make it easier to locate errant "categories" attributes so we can quickly resolve the problem, without restricting availability of the sample from our end-users.

A sample browser should not inherently assume a tree with a limited depth; however, there is a practical visual limit. For the purpose of implementation, the sample browser should assume an infinite depth is possible, but apply a finite depth that is specified by the UX/DX team and which can be easily changed in your code. Also, apply a "safe limit" depth that limits the the UX/DX limit.

sampleTreeLimitUI = <depth-specified-by-UX/DX-team> ;
sampleTreeLimitSafe = 10 ;

if( (sampleTreeLimitUI > sampleTreeLimitSafe) || (sampleTreeLimitUI < 2) )
    sampleTreeLimitUI = sampleTreeLimitSafe ;

`"toolchain"`

This attribute is only recognized by IDE sample browsers.

At first glance, "toolchain" appears to be a dependency or a directive that forces the use of a specific compiler. In fact, this attribute only tells the IDE which compiler to use as the IDE "indexer" (aka the "intellisense" feature in the IDE).

NOTE: See the "compiler|" heading in the "dependencies" section of this document for a way to specify a compiler dependency.

The "toolchain" attribute does not specify the compiler that is used to build the sample project. A sample's build files (e.g., Visual Studio project files, CMake build files, Makefile build files, etc.) dictate which compiler builds a sample's sources. Within some IDEs there is a need to specify the compiler to be used as the "indexer" ("intellisense") by the IDE, to aid developers with code hints in the edit view. Normally, the "toolchain" attribute should match the compiler that is being utilized by the build files provided with the sample; but it is not absolutely necessary and may be omitted.

In reality, only specifying a C or C++ compiler has any effect when including the "toolchain" attribute. Despite this, the allowed values for the purpose of sample.json validation are (as of July 2021):

"dpcpp"
"dpcpp-cl" (Windows only)
"cl" (Windows only)
"icx"
"icpx"
"clang"
"clang++"
"icc"
"icpc"
"ifx"
"ifort"
"gcc" (Linux only)
"g++" (Linux only)
"jupyter"

`"languages"`

This attribute is recognized by all sample browsers.

NOTE: This attribute may be simplified in a future oneAPI release.

The following array of objects have been defined. Only one is expected to be present in the "languages" array:

{"c":{}} (do not use)
{"cpp":{}}
{"fortran":{}}
{"maven":{}} (do not use)
{"java":{}} (do not use)
{"javascript":{}} (do not use)
{"python":{}}

At this time (May, 2021), only the {"cpp":{}}, {"python":{}} and {"fortran":{}} language objects are relevant to the oneAPI sample feed and only the oneapi-cli and VSCode sample browsers will deliver Fortran and Python samples.

Some older versions of the Eclipse IDE sample browser inspected the {"cpp":{}} language object for the "make" property, but only if it did not find a valid "builder" attribute. This behavior has been deprecated and should not be used in your sample.json file. Use the "builder" attribute to indicate that your sample is a Makefile sample.

NOTE: As of the beta06 release it is safe to stop using the language object to indicate that a sample is a Makefile project.

Following is an example of the deprecated behavior described in the paragraph above that you should not use to designate a Makefile sample:

"cpp": {"properties": {"projectOptions": [{"projectType": "make"}] } }

NOTE: Use the {"cpp":{}} object for both C and C++ project types.

`"dependencies"`

This attribute is recognized by all sample browsers.

The "dependencies" array specifies which tools or "components" are needed to build and run a sample. The names of the dependent components must match exactly their installed directory names (e.g. "mkl", "tbb", "vtune", etc.).

A test is performed by the sample browsers to determine if the required dependencies have been installed and are available on a user's development system. If one or more dependencies are found to be missing, an appropriate warning is presented to the user when they are viewing and/or creating a sample project based on the sample.

NOTE: Lack of a dependency does not prevent a project from being created, it simply serves as a way to let the user know that the new sample project may fail to build or run correctly unless they resolve the missing dependencies.

As of the 2021.2 oneAPI release, the complete set of oneAPI product toolkits included the following component folders (based on a full Linux install):


ospray_studio	tensorflow	advisor	pytorch	oidn
intel-eclipse-ide	debugger	ccl	clck	ipp
system_debugger	intelpython	itac	mkl	dnnl
conda_channel	rkcommon	openvkl	tbb	ippcp
dev-utilities	inspector	ospray	dal	vpl
eclipse-iot-plugins	compiler	vtune	mpi	iLiT
rkutil	dpcpp-ct	embree	modelzoo	dpl

If a component folder name changes (either in case or spelling) it must be updated inside any sample.json files that references it. The sample browsers do not attempt to perform an approximate match. Thus, an incorrectly spelled dependency in a "dependencies" list will always appear as a missing dependency for the sample associated with that sample.json file.

`pkg|` (Linux only)

On Linux, external dependencies can be managed using package config (pkg-config). Normally, an entry in the "dependencies" array is simply mapped to a oneAPI component directory. However, if it is preceded with pkg| then it means the sample browser will check for the named package.

The full syntax is:

pkg|<package-name>|<url>

where the <url> will be passed to the user in the event the package is not found. The <url> is optional (though highly recommended).

Example:

"dependencies":["pkg|mraa|https://github.com/intel-iot-devkit/mraa","mkl"]

`compiler|`

The compiler| dependency can be used to name a specific Intel compiler dependency from the following list:

dpcpp
dpcpp-cl (Windows only, use dpcpp instead)
icx
icpx
icc
icpc
ifx
ifort

For example, if a sample specifically depends on icpc for compilation, the sample.json file can specify that this Intel compiler is required by way of the compiler|icpc dependency declaration, as part of the "dependencies" array.

Normally, an entry in the "dependencies" array is mapped directly to a oneAPI component folder name. But the compiler component must be handled differently because multiple "sub-components" (compilers) are embedded inside the compiler component's folder.

NOTE: The dpcpp-cl compiler is unique to Windows. For the purposes of specifying a dependency on the dpcpp-cl compiler, use dpcpp. This will minimize alert notifications across multiple OSes. This attribute does not specify which compiler is used to compile your sample! Your build files (VS proj, CMakeLists.txt or Makefile) control which compiler is used. This feature is only used to alert user's if the compiler is present.

The full syntax is:

`compiler|<compiler-name>`

Example:

"dependencies":["compiler|icc","mkl"]

NOTE: See also the "toolchain" section of this document.

`"targetDevice"`

This attribute is not currently used by the sample browsers.

NOTE: As this attribute relates to the sample browsers, it is under construction and subject to change. What is described below is proposed behavior for sample browsers. The behavior will be updated as this option is further refined.

This attribute is meant as a sample filter, not as a requirement of the development system. It is intended to describe which hardware the sample is meant to showcase. Use it to have the sample browsers filter the samples presented to the end user; for example, by using check boxes to filter the view of samples based on the "targetDevice" array.

Following are examples showing how the "targetDevice" attribute can be used to filter samples displayed by the samples plugin:

CPU only - "targetDevice": ["CPU"]
CPU/GPU - "targetDevice": ["CPU", "GPU"]
CPU/FPGA - "targetDevice": ["CPU", "FPGA"]

The CPU attribute is meant to be used when the sample is designed to showcase special CPU features.

An FPGA tutorial might require “FPGA” as a "targetDevice", in which case you would need either the emulator or a real FPGA to run the sample.

Alternatively, the "vector add" sample might list "CPU", "GPU" and "FPGA" since the generated kernel code is supported by all three hardware devices.

`"sampleReadmeUri"`

This attribute is recognized by all sample browsers.

This optional string attribute specifies the location of an on-line, publicly-available README file that describes the sample. It is only required if the default location of the sample's README file is not available.

NOTE: The "sample aggregator" will attempt to automatically add this attribute by providing a link to a README file located in your sample's top-level Git folder.

If this attribute is not present, or is undefined, the "sample aggregator" will assume that a README file located in the root of the sample's Git repo is the appropriate README file for the sample. This auto-identified README file is presented to the user as a link by the sample browser and, therefore, must be accessible as a publicly available link that can be displayed in the user's local browser.

For those situations where a sample's git repo does not contain a useful README file, or when the sample's Git repo is private and is not publicly available, this attribute can be used to point to an appropriate page that is publicly available and germane to the sample. For example a sample-specific page on the Intel Developer Zone:

`"sampleReadmeUri": "https://software.intel.com/my-custom-readme.html"`

`"os"`

This attribute is recognized by all sample browsers.

Supported array elements are:

"linux"
"windows"
"darwin"

The optional "os" attribute specifies on which OS a sample can be built and run. You can use it to limit the sample's visibility to a subset of supported operating systems. If this value is not present it is assumed the sample will compile and run on all supported operating systems.

Specifying all supported operating systems is equivalent to accepting the default when the attribute is not present in your sample.json file.

NOTE: The string "darwin" refers to the macOS operating system (aka OSX or macOS), meaning that the sample can be built on and the resulting binary can be run on an Apple Mac development system.

NOTE: At this time (May, 2021), there is no support for importing samples into the Apple Xcode development tools. Only command-line console application development is supported by the oneAPI tools on "darwin" systems. The Xcode command-line development tools, however, are required as adjunct tools by the Intel compilers.

`"altindex":true`

This optional attribute is only recognized by the Eclipse sample browser.

The "altindex" attribute is optional. It is meant for dealing with special case problems associated with the Eclipse "intellisense" feature. The only value defined for this attribute is true. If present, this attribute forces the Eclipse sample browser to configure the Eclipse indexer to use an alternate indexing scheme, rather than the scheme prescribed by the preferred toolchain compiler specified by the "builder" attribute.

This attribute is a temporary solution, meant to be used only until those Eclipse issues encountered when using the preferred builder have been resolved. This attribute does not impact the compiler that is used to actually build the sample, it only impacts the indexer feature that manages how potential errors are displayed in the edit window (aka "intellisense). In other words, the "builder" attribute defines the actual toolchain specified in the Eclipse C/C++ project; the presence of this attribute may result in an "override" of the default Eclipse indexer configuration and is meant to eliminate false positives generated by a faulty Eclipse indexer.

NOTE: Sample authors should never add the "altindex" attribute to their sample.json files unless they have been directed to do so by the samples working group. Such a directive would likely happen via a merge request to the sample's online git repo.

`"builder"`

This attribute is only recognized by IDE sample browsers.

The optional "builder" attribute is only meaningful for IDE sample browsers (e.g., Eclipse and Visual Studio). The oneapi-cli sample browser copies the selected sample into a folder on the user's disk and leaves the tasks of building and running the sample to be performed by the end user, via the CLI. When using oneapi-cli the user's build options will depend on what build instructions have been provided within the sample project (CMakeLists.txt, Makefile, etc.).

NOTE: The preferred build tool is CMake, because it works well across Windows, Linux and Mac operating systems, and with a variety of compilers.

Recognized "builder" tool name IDs are (in no particular order):

"cli" (see notes below)
"ide" (Visual Studio only)
"make" (Linux and Mac only)
"cmake" (default)

The presence of the "cli" array element (located anywhere in the "builder" array) causes the sample to be ignored by IDE sample browsers. See the example notes, below, for more details.

The "ide" builder implies that the sample contains IDE-specific project files that will be imported and used by the IDE to manage building the sample (e.g., a set of Visual Studio solution and project files are included in the root of the sample).

Specifying "make" means this sample includes a Makefile or makefile build file in the sample's root folder.

NOTE: The Visual Studio sample browser does not support make projects, which means only the Eclipse IDE (or CLI) will work with a Makefile project.

NOTE: Visual Studio Code (aka VSCode) is not considered an "IDE" and, therefore, the VSCode sample browser does not support the "ide" builder label. VSCode is a smart editor and is best used in conjunction with command-line (CLI) development tools. VSCode Workspace settings are not currently supported if they are included with a sample project.

The default builder is "cmake" and applies if the the "builder" attribute is not provided, is not recognized, or if the conditions needed to satisfy the specified builder(s) are not satisfied (e.g., no IDE project files are found, no Makefile is found, etc.). Specifying or defaulting to "cmake" means a CMakeLists.txt file can be found in the sample's root folder.

Providing an array of "builder" strings means you can specify a priority of builders. For example, if only Visual Studio solution and project files (.sln, etc.) are provided with your sample, specifying "ide" will work on Windows but not on Linux, because only Visual Studio on Windows supports the "ide" builder. In that case, providing a CMakeLists.txt file insures that the default builder, "cmake", will be selected for non-Windows builds. Removing the "builder" attribute entirely means any IDE-specific build file(s) included with your sample will be ignored, because "cmake" is the default builder.

NOTE: The Eclipse sample browser does not support importing Eclipse project files (.project and .cproject). There are significant problems associated with the management of Eclipse projects created using this technique, which are due to problems with the internal design of the Eclipse project management system.

The "builder" attribute can be confusing. The following examples show how Eclipse and Visual Studio will interpret a list of "builder" attribute array elements. Array elements are evaluated in order of their appearance in the array (except "cli"). The [^#] notation indicates a footnote:

"builder": ["<builder-id>", "cli", "<builder-id>"]
IF ( ("cli" is present anywhere in array) && (IDE sample browser) )[^1]
    ignore the sample, do not present it in the list of IDE samples

"builder": ["ide"]
IF (IDE project files are available in the sample, use them)[^2]
ELSE (create an IDE CMake project, the default action)[^4]

"builder": ["ide","cmake"]
IF (IDE project files are available in the sample, use them)[^2]
ELSE (create an IDE CMake project, the default action)[^4]

"builder": ["ide","make"]
IF (IDE project files are available in the sample, use them)[^2]
ELSE IF (Makefile or makefile is present, create an IDE Makefile project)[^3]
ELSE (create an IDE CMake project, the default action)[^4]

"builder": ["make"]
IF (Makefile or makefile is present, create an IDE Makefile project)[^3]
ELSE (create an IDE CMake project, the default action)[^4]

IF ("builder" attribute is not present or is invalid)
    create an IDE CMake project[^4]

FOOTNOTES to the `"builder"` attribute examples:

[^1]: The "cli" string causes the sample to be ignored by IDE sample browsers. This means the sample will only be presented by the oneapi-cli sample browser and the VSCode sample browser. This should only be used when the sample is only suitable for building at the CLI. For example, Python samples are not supported by either the Visual Studio or Eclipse sample browsers.

[^2]: At this time, the only native IDE project files that are supported are Visual Studio solution/project files. Eclipse project files, if present, will be ignored.

[^3]: IDE Makefile projects are only supported by Eclipse on Linux. Visual Studio has inconsistent support for IDE Makefile projects. Additionally, it is very difficult to create cross-OS makefiles that work well with both Linux/Unix make and Microsoft nmake.

[^4]: CMake is the default IDE project type. Obviously, if the IDE defaults to creating an IDE CMake project it is assumed there are appropriate CMake build files included with the project, otherwise that IDE CMake project will not work when the user attempts to build it. Regardless, if requested, or due to selection as the default builder, the sample browser should create a CMake project, so the end-user can, at minimum, review the sample code.

NOTE: CMake is the preferred builder. When creating an IDE CMake project the CMake files that are used to build at the CLI are the same CMake files used by the IDE CMake project. Both Eclipse and Visual Studio support IDE CMake projects. CMake is the best way to insure that the build results a user gets at the CLI is consistent with those they get when using a supported IDE.

When creating an IDE CMake project in Visual Studio a "hybrid" Visual Studio CMake project is created. The user interacts with it just like a Visual Studio MSBuild project, with many build features accessible via the standard Visual Studio project interface. Support for IDE CMake projects is built into Visual Studio and is actively developed and supported by Microsoft for both Windows and Linux targets (think WSL on Windows 10).

Following is a pseudo-code example of how the IDE sample browsers should parse the "builder" array (break means leave the for loop):

if( "builder" array contains "cli" )
   quit and do not display the sample

projType = "cmake"
for( i = 0; builder[i] != ""; i++ ) {
  if( builder[i] is something IDE can implement ) {
    projType = builder[i]
    break
  }
}

`"guid"`

This attribute is ignored by all sample browsers.

See the sample.json Specification wiki page for details.

`"ciTests"`

This attribute is ignored by all sample browsers.

See the sample.json CI Test Object wiki page for details.

Additional Information on DPC++ topics can be found in the book(pdf):

Data Parallel C++ Mastering DPC++ for Programming of Heterogeneous Systems using C++ and SYCL

sample.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sample Browser

What is the Sample Browser

Use of the `samples.json` File by the Sample Browsers

A Typical `sample.json` File

`sample.json` Attribute Details

`"name"`

`"description"`

`"categories"`

`"toolchain"`

`"languages"`

`"dependencies"`

`pkg|` (Linux only)

`compiler|`

`"targetDevice"`

`"sampleReadmeUri"`

`"os"`

`"altindex":true`

`"builder"`

FOOTNOTES to the `"builder"` attribute examples:

`"guid"`

`"ciTests"`

Clone this wiki locally

Sample Browser

What is the Sample Browser

Use of the samples.json File by the Sample Browsers

A Typical sample.json File

sample.json Attribute Details

"name"

"description"

"categories"

"toolchain"

"languages"

"dependencies"

pkg| (Linux only)

compiler|

"targetDevice"

"sampleReadmeUri"

"os"

"altindex":true

"builder"

FOOTNOTES to the "builder" attribute examples:

"guid"

"ciTests"

Clone this wiki locally

Use of the `samples.json` File by the Sample Browsers

A Typical `sample.json` File

`sample.json` Attribute Details

`"name"`

`"description"`

`"categories"`

`"toolchain"`

`"languages"`

`"dependencies"`

`pkg|` (Linux only)

`compiler|`

`"targetDevice"`

`"sampleReadmeUri"`

`"os"`

`"altindex":true`

`"builder"`

FOOTNOTES to the `"builder"` attribute examples:

`"guid"`

`"ciTests"`