Each sample requires a sample.json file that is used by the sample browsers and the sample aggregator to determine how to name and describe a sample, as well as how to create a buildable project. The sample.json file also includes instructions used by the sample working group's CI system to regularly test your sample. The sample.json file is located in the root of your sample.

NOTE: If you are not ready to distribute your sample via the sample browsers, do not include a file named sample.json in your sample's top-level project folder. The presence of the sample.json file tells the "sample aggregator" to prepare a sample for delivery by the sample browsers.

Additional information about the sample.jsonfile and its interpretation by the various Sample Browsers, can be found on this wiki page.

For most samples, your sample.json will look like one of the following.

This sample includes a CMakeLists.txt file as well as predefined Visual Studio solution and project files. It will result in the following project types, depending on the sample browser used to create the project:

• oneapi-cli > clones sample to the disk for CLI builds.
• Eclipse > creates an Eclipse cmake4eclipse project.
• Visual Studio > imports the Visual Studio solution.
• Visual Studio Code > clones sample to the disk vis-à-vis CLI builds.

{
  "name": "My CMake or Visual Studio Sample",
  "description": "Simple CMake or Visual Studio project...",
  "categories": ["UI/UX/Defined/Category/List"],
  "os": ["linux","windows"],
  "builder": ["ide","cmake"],
  "languages": [{"cpp":{}}],
  "toolchain": ["dpcpp"],
  "guid": "01234567-89AB-CDEF-0123-456789ABCDEF"
}

"os": ["linux","windows"] means the the sample is buildable on Windows and Linux development systems.

"builder": ["ide","cmake"] means an IDE sample browser (e.g., Visual Studio) will check for IDE-specific project files and import the project. If there are no compatible IDE project files, the IDE sample browser will create an IDE-specific CMake project, instead.

NOTE: Only the Visual Studio sample browser checks for and imports project and solution files. Neither the Eclipse sample browser nor the VSCode sample browser support importing IDE-specific project files. They will, however, import cmake and make build instructions.

"toolchain": ["dpcpp"] means the IDE project created will use the DPC++ compiler to "index" the sample project (i.e., to drive the "Intellisense" feature in an IDE). It does not specify the compiler to be used for building the sample project, your build files do that, it only tells the IDE (VS or Eclipse) what compiler to use for generating intellisense hints.

NOTE: Do not use the GUID shown in the examples on this page in your sample.json file. See the "guid" attribute section on this page for more details.

This sample includes a Makefile (or makefile) build file as well as predefined Visual Studio solution and project files. It will result in the following project types, depending on the sample browser used to create the project:

• oneapi-cli > clones sample to the disk for CLI builds.
• Eclipse > creates an Eclipse Make project.
• Visual Studio > imports the Visual Studio solution.
• Visual Studio Code > clones sample to the disk vis-à-vis CLI builds.

{
  "name": "My Make or Visual Studio Sample",
  "description": "Building with make or a Visual Studio project...",
  "categories": ["UI/UX/Defined/Category/List"],
  "dependencies": ["mkl"],
  "os": ["linux","windows","darwin"],
  "builder":["ide","make"],
  "languages": [{"cpp":{}}],
  "toolchain": ["icc"],
  "guid": "01234567-89AB-CDEF-0123-456789ABCDEF"
}

"dependencies": ["mkl"] means the sample browser will check to see if the "mkl" component is installed and will issue a warning if it is not found. It will not stop the creation of the sample project nor prevent the user from attempting to build the sample if any of the listed dependent components are not found.

"os": ["linux","windows","darwin"] means the the sample is buildable on Windows, Linux and macOS (Darwin) development systems.

"builder": ["ide","make"] means an IDE sample browser (e.g., Visual Studio or Eclipse) will check for IDE-specific project files and use them. If there are no compatible IDE project files, the IDE sample browser will create an IDE-specific Makefile project, instead.

NOTE: Only the Visual Studio sample browser checks for and imports project and solution files. The Eclipse sample browser does not support importing IDE-specific project files. Eclipse will, however, import cmake and make projects.

"toolchain": [icc"] means the IDE project created will use the ICC compiler to "index" the sample project (i.e., to drive the "Intellisense" feature in an IDE). It does not specify the compiler to be used for building the sample project, your build files do that, it only tells the IDE (VS or Eclipse) what compiler to use for generating intellisense hints.

This sample includes a CMakeLists.txt file. It does not contain any IDE-specific project files. It will result in the following project types, depending on the sample browser used to create the project:

• oneapi-cli > clones sample to the disk for CLI builds.
• Eclipse > creates an Eclipse cmake4eclipse project.
• Visual Studio > creates a Visual Studio cmake project (see note).
• Visual Studio Code > clones sample to the disk vis-à-vis CLI builds.

{
  "name": "My CMake Sample",
  "description": "How to build CMake using Visual Studio...",
  "categories": ["UI/UX/Defined/Category/List"],
  "os": ["linux","windows"],
  "builder": ["cmake"],
  "languages": [{"cpp":{}}],
  "toolchain": ["dpcpp"],
  "guid": "01234567-89AB-CDEF-0123-456789ABCDEF"
}

"os": ["linux","windows"] means the the sample is buildable on Windows and Linux development systems.

"builder": ["cmake"] means an IDE sample browser (e.g., Visual Studio or Eclipse) will create an IDE-specific CMake project, ignoring any IDE-specific project files that might be present in the sample.

NOTE: Visual Studio CMake projects are not recommended, at this time, due to issues related to CMake on Windows and the Intel DPCPP compiler. This build option will be supported when those issues have been resolved.

"toolchain": ["dpcpp"] means the IDE project created will use the DPC++ compiler to "index" the sample project (i.e., to drive the "Intellisense" feature in an IDE). It does not specify the compiler to be used for building the sample project, your build files do that, it only tells the IDE (VS or Eclipse) what compiler to use for generating intellisense hints.

This sample includes a Makefile and does not contain any IDE-specific project files. It will result in the following project types, depending on the sample browser used to create the project:

• oneapi-cli > clones sample to the disk for CLI builds.
• Eclipse > creates an Eclipse cmake4eclipse project.
• Visual Studio > ignores the project (not visible in sample browser).
• Visual Studio Code > clones sample to the disk vis-à-vis CLI builds.

{
  "name": "My Makefile Sample",
  "description": "How to build a Makefile sample on Linux...",
  "categories": ["UI/UX/Defined/Category/List"],
  "os": ["linux","darwin"],
  "builder": ["make"],
  "languages": [{"cpp":{}}],
  "toolchain": ["dpcpp"],
  "guid": "01234567-89AB-CDEF-0123-456789ABCDEF"
}

"os": ["linux","darwin"] means the the sample is buildable on Linux development and macOS ("Darwin") systems.

NOTE: Makefile samples are currently only supported on Linux and macOS systems.

"builder": ["make"] means an IDE sample browser (e.g., Visual Studio or Eclipse) will create an IDE-specific user-managed Makefile project, ignoring any IDE-specific project files that might be present in the sample.

"toolchain": ["dpcpp"] means the IDE project created will use the DPC++ compiler to "index" the sample project (i.e., to drive the "Intellisense" feature in an IDE). It does not specify the compiler to be used for building the sample project, your build files do that, it only tells the IDE (VS or Eclipse) what compiler to use for generating intellisense hints.

This sample may include a variety of build files (including a CMake build file is highly recommended). It does not require IDE-specific project files or IDE-specific sample.json attributes. It will result in the following project types, depending on the sample browser used to create the project:

• oneapi-cli > clones sample to the disk for CLI builds.
• Eclipse > ignores the project (not visible in sample browser).
• Visual Studio > ignores the project (not visible in sample browser).
• Visual Studio Code > clones sample to the disk vis-à-vis CLI builds.

{
  "name": "My CLI Sample",
  "description": "How to create a CLI-only sample...",
  "categories": ["UI/UX/Defined/Category/List"],
  "os": ["linux","windows","darwin"],
  "builder": ["cli"],
  "languages": [{"cpp":{}}],
  "guid": "01234567-89AB-CDEF-0123-456789ABCDEF"
}

"os": ["linux","windows","darwin"] means the the sample is buildable on Windows, Linux and macOS ("Darwin") development systems.

"builder": ["cli"] means the the sample is only visible in the oneapi-cli and Visual Studio Code sample browsers. Including "cli" anywhere in the "builder" array will cause the IDE sample browsers (Visual Studio and Eclipse) to ignore the sample; meaning, they will not display a "cli" sample in their tree of available samples.

This sample builds on the "CMake Only Sample" shown previously, above, but does not require that the sample be a CMake sample; it can be any type of sample, a CMake sample is being used for illustration.

This sample assumes that the public git repo where the sample is stored contains multiple samples that share one or more common folders and/or files. If you were to clone the sample repo you would get multiple samples with a top-level build file that is used to build any or all of the samples. When building those samples they would utilize the common folder, typically for holding common libraries, shared sources, etc.

In addition to the JSON entries that are needed to describe the sample, a special "commonFolder" object must be defined and included in the sample.json file:

{
  "name": "My Common Folder CMake Sample",
  "description": "A sample derived from a repo with shared folders.",
  "categories": ["UI/UX/Defined/Category/List"],
  "os": ["linux","windows","darwin"],
  "builder": ["cmake"],
  "languages": [{"cpp":{}}],
  "toolchain": ["dpcpp"],
  "commonFolder": {
    "base": "..",
    "include": [
      "sample-folder-name",
      "common-folder-name",
      "another-common-folder-name",
      "CMakeLists.txt",
      "README.md"
    ],
    "exclude": [
      "sample-folder-name/test.sh"
    ]
   },
  "guid": "01234567-89AB-CDEF-0123-456789ABCDEF"
}

"commonFolder": {} is a container in which to include the "base", "include" and "exclude" properties. The commonFolder property is optional, meaning that only samples that require this common folder feature need to provide it.

"base": <string> specifies the location of the "top folder" in the sample relative to the sample's sample.json file. Think of it as the "cwd" for the folder and/or file names listed by the "include" and "exclude" properties. This property is required if the "commonFolder" object is present.

NOTE: It would be very unusual to see a "base" property that specifies something other than the ".." string. The typical "common folder sample" has only one level above the sample. If there were more levels to the "top" of the sample folder structure, it would look like "../.." and so on.

"include":[<array>,<of>,<strings>] represents a list of items (folders or files) that are named relative to the "base" property and will be included in the sample that is delivered by the various sample browsers. This property is required if the "commonFolder" object is present.

NOTE: The folder that contains the core sample source must be explicitly named (e.g., sample-folder-name above), in addition to any files and folders located outside of the sample folder. Specifying a folder in the "include" property means that the named folder and all files and folders within that named folder are included as part of the sample. Specifying a file in the "include" property only includes that file. This property is required if the "commonFolder" object is present, it is expected to reference at least one folder, the sample folder.

"exclude":[<array>,<of>,<strings>] represents a list of items (folders or files) that are named relative to the "base" property and are excluded from the sample that is delivered by the various sample browsers. This property is optional.

NOTE: If a folder or file is named by both the "include" and the "exclude" property the "exclude" property wins. That is, regardless of a folder or file's presence in the "include" array, the "exclude" array has priority. Like the "include" property, naming a folder in the "exclude" property means that folder and all sub-folders and files contained within it are excluded.

In addition to the attributes shown in the examples above, there are additional sample.json fields that can be used to direct the sample browsers regarding the nature of the sample project to be created. These attributes are summarized below.

A detailed description of the sample.json attributes can be found on the Sample Browser Behavior wiki page.

NOTE: Do not copy and paste this sample.json file into your sample project. Several of the object attributes contain lists of possible values; in most cases those lists will not be appropriate for your sample.

{
  "name": "<sample-name>",
  "description": "<sample-description>",
  "categories": ["Toolkit/<toolkit_name>/<component_name>/<sample_type>"],
  "toolchain": ["dpcpp", "icc", "gcc", "cl"],
  "languages": [{"c":{}}, {"cpp":{}}, {"fortran":{}}, {"maven":{}}, {"java":{}}, {"javascript":{}}, {"python":{}}],
  "dependencies": ["mkl", "tbb", "mpi", "vtune", "..."],
  "targetDevice": ["CPU", "GPU", "NNP", "FPGA"],
  "sampleReadmeUri": "https://software.intel.com/my-custom-readme.html",
  "os": ["linux", "windows", "darwin"],
  "builder": ["cli", "ide", "make", "cmake"],
  "altindex": true,
  "guid": "01234567-89AB-CDEF-0123-456789ABCDEF"
}

The name of your sample, which will be presented by the sample browser.

A short (one or two sentences) describing your sample, which will be presented by the sample browser.

Samples are presented within the sample browsers in a tree view, where categories are represented as linked nodes and sample names are leaf nodes. The category string defines the location of your sample within this tree hierarchy, as displayed by the sample browser. Think of it as a directory tree of samples. The categories string does not include the name of the sample, only the tree path in which the sample should be located.

See this sample tree for an example of how the "categories" array works.

Multiple array entries are supported and should be used when there is a need to show the same sample in multiple locations in the sample browser tree.

The "toolchain" attribute specifies the compiler to be used to "index" the sample sources for "intellisense" features. In practice, it only has meaning for C/C++ projects created in Visual Studio or Eclipse. It is not specifying the compiler to be used for building the sample project, your build files do that, it is only used to tell the IDE (VS or Eclipse) which compiler to use for generating intellisense hints. It has a default value of "gcc" on Linux and "cl" on Windows, if not specified. See the "toolchain" section of the Sample Browser Behavior document for more details.

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.

This attribute is recognized by all sample browsers.

The "dependencies" array specifies which tools or "components" are needed to build and run your sample. The names of any dependent oneAPI components will match 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 present on a user's development system. If one or more dependencies are found to be missing, an informational message is presented to the user when they are viewing and/or creating a sample project based on the sample. 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 not build or run correctly until they have resolved the missing dependencies.

NOTE: The exact name and spelling of oneAPI component dependencies is determined by looking at the component folders as they are installed by the oneAPI installer. For the current list of dependency review the component folder names in a current installation of the oneAPI toolkits.

On Linux, external dependencies can also be asserted via package config (pkg-config). Normally, an entry in the "dependencies" array is simply mapped to a directory. But if it is preceded with pkg| then it can name a 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 present. The <url> is optional (though highly recommended).

Example:

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

The compiler component can contain multiple Intel compilers (e.g., dpcpp, dpcpp-cl, icx, icpx, icc, icpc, ifort and ifx). If a sample depends on, for example, ICC or Fortran, it can specify it exactly with the compiler| dependency declaration. Normally, an entry in the "dependencies" array is exactly matched to a component folder name. But if that name is preceded with compiler| then it can be used to name a specific compiler. NOTE: dpcpp-cl is only present on Windows and can be ignored for the purposes of the dependencies attribute, use dpcpp instead.

compiler|<compiler-name>

Example:

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

See the compiler| section of the Sample Browser Behavior document for more details.

This required attribute is used as a sample filter, not as a requirement of the development system. It is intended to describe which hardware devices the sample is meant to showcase. Valid values for this key are:

"targetDevice": ["CPU", "GPU", "NNP", "FPGA"]

If your sample provides build options that are relevant to multiple compute devices, indicate that by including multiple device names in the array.

This optional string can be used to reference a non-default publicly available readme file location. Typically this is used when the README.md in the sample repo is not publicly available or is not an appropriate readme for the sample. For example:

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

If no "sampleReadmeUri" is provided, the sample aggregator will attempt to automatically create this attribute by providing a link to a README file located in your sample's top-level Git folder.

The optional "os" string specifies that a sample can only be built and run on a subset of the supported OSes. If this value is not included in your sample.json file it is assumed the sample will compile and run on all OSes supported by the toolkits for that release. Default expected values are shown in the example above.

The optional "builder" attribute indicates the preferred builder. The default builder is "cmake" and applies if the the "builder" attribute is not provided, the content of the "builder" array is not recognized or the conditions needed to satisfy the specified builder(s) are not satisfied (e.g., "ide" specified but no IDE project files are found, etc.). More than one "builder" can be specified in the "builder" array; the order of the array elements is important, as the samples browsers will evaluate the list of provided builders in the order presented by the array.

NOTE: If a builder is specified in the "builder" array without the corresponding build files needed to build the sample, that builder will be ignored by the sample browser.

An "ide" builder value means the sample contains IDE-specific project files that will be imported into the IDE and used to perform and manage the build (e.g., a Visual Studio solution file or an Eclipse project file is included in the root of the sample).

NOTE: Only the Visual Studio sample browser checks for and imports project and solution files. Neither the Eclipse sample browser nor the VSCode sample browser support importing project files. They will, however, import cmake and make projects.

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

NOTE: Makefile samples are not supported on Windows systems, at this time, due to the difficulty insuring that your makefile will work properly with nmake on Windows and with make on Linux and macOS systems.

Specifying "cmake" (the default builder) means this is a CMake-managed project and there is a CMakeLists.txt file in the root of the sample. Naming "cmake" as the default builder means that even if a CMakeLists.txt file is not provided in the sample's root folder, the sample browser will still attempt to create a CMake project, but it will likely not be buildable.

Specifying "cli" anywhere in the "builder" array list makes the sample visible only in the oneapi-cli tool (the CLI sample browser) and Visual Studio Code; meaning the IDE sample browsers (Visual Studio and Eclipse) will ignore the sample and will not display it in their list of available samples.

NOTE: See the examples at the beginning of this page for typical usage. For a more detailed description, see the "builder" section of the Sample Browser Behavior wiki page.

The optional "altindex" attribute is meant for handling special case problems associated with the Eclipse "intellisense" (aka "indexer") feature. The only value defined for this attribute is true. If present, this attribute instructs the sample browser to configure the Eclipse indexer to use an alternate indexer toolchain compiler, rather than using the preferred toolchain compiler specified by the "builder" attribute. Using this attribute is a temporary solution to an Eclipse problem that is generally restricted to a small number of dpcpp sample.

This attribute does not impact the compiler that is used to actually build the sample, it only impacts the Eclipse indexer (aka "intellisense) feature that manages how potential C/C++ syntax errors are displayed in the Eclipse edit window.

NOTE: Do not add the "altindex" attribute to your sample.json file unless you have been directed to do so by the IDEV team. A request to add this flag would likely happen through a merge request in your sample's git repo.

This field is used by the sample CI testing system and the sample aggregation system to uniquely identify your sample. The GUID may be used to enable and disable samples from tests and/or distribution. The sample author's only responsibility is to assign a GUID to their sample.

NOTE: Once assigned, the GUID should not be changed unless you are specifically directed to do so by the samples working group.

Go to https://www.guidgenerator.com to generate a GUID for your sample.

Check the Uppercase and Hyphens boxes, all others should be cleared. The GUID field in your sample.json file should have a format similar to the following:

"guid": "01234567-89AB-CDEF-0123-456789ABCDEF"

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