Each sample requires asample.json file that is used by thesamplebrowsers and thesample aggregator to determine how to name and describe asample, as well as how to create a buildable project. Thesample.json filealso includes instructions used by the sample working group's CI system toregularly test your sample. Thesample.json file is located in the root ofyour sample.

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

Additional information about thesample.jsonfile and its interpretation bythe various Sample Browsers, can be found on thiswiki page.

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

This sample includes aCMakeLists.txt file as well as predefined VisualStudio solution and project files. It will result in the following projecttypes, depending on thesample 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 andLinux 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 areno compatible IDE project files, the IDE sample browser will create anIDE-specific CMake project, instead.

NOTE: Only the Visual Studio sample browser checks for and importsproject and solution files. Neither the Eclipse sample browser nor the VSCodesample 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 buildingthe sample project, your build files do that, it only tells the IDE (VS orEclipse) what compiler to use for generating intellisense hints.

NOTE: Do not use the GUID shown in the examples on this page in yoursample.json file. See the "guid" attribute section on this page formore details.

This sample includes aMakefile (ormakefile) build file as well aspredefined Visual Studio solution and project files. It will result in thefollowing project types, depending on thesample browser used to create theproject:

• 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 thesample browser will check to see if the"mkl" component is installed and will issue a warning if it is not found. Itwill not stop the creation of the sample project nor prevent the user fromattempting to build the sample if any of the listed dependent components arenot found.

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

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

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

"toolchain": [icc"] means the IDE project created will use the ICCcompiler 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 buildingthe sample project, your build files do that, it only tells the IDE (VS orEclipse) what compiler to use for generating intellisense hints.

This sample includes aCMakeLists.txt file. It doesnot contain anyIDE-specific project files. It will result in the following project types,depending on thesample 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 andLinux development systems.

"builder": ["cmake"] means an IDE sample browser (e.g., Visual Studio orEclipse) will create an IDE-specific CMake project, ignoring any IDE-specificproject 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. Thisbuild 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 buildingthe sample project, your build files do that, it only tells the IDE (VS orEclipse) what compiler to use for generating intellisense hints.

This sample includes aMakefile and doesnot contain any IDE-specificproject files. It will result in the following project types, depending on thesample 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 Linuxdevelopment and macOS ("Darwin") systems.

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

"builder": ["make"] means an IDE sample browser (e.g., Visual Studio orEclipse) will create an IDE-specific user-managed Makefile project, ignoringany 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 buildingthe sample project, your build files do that, it only tells the IDE (VS orEclipse) what compiler to use for generating intellisense hints.

This sample may include a variety of build files(including a CMake buildfile is highly recommended). It does not require IDE-specific project filesor IDE-specificsample.json attributes. It will result in the followingproject types, depending on thesample 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 onWindows, Linux and macOS ("Darwin") development systems.

"builder": ["cli"] means the the sample is only visible in the oneapi-cliand 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 theirtree of available samples.

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

This sample assumes that the public git repo where the sample is storedcontains multiple samples thatshare one or morecommon folders and/orfiles. If you were to clone the sample repo you would get multiple sampleswith a top-level build file that is used to build any or all of the samples.When building those samples they would utilize thecommon folder, typicallyfor holding common libraries, shared sources, etc.

In addition to the JSON entries that are needed to describe the sample, aspecial"commonFolder" object must be defined and included in thesample.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. ThecommonFolder property isoptional, meaning that only samples that require thiscommon folder featureneed to provide it.

"base": <string> specifies the location of the "top folder" in the samplerelative to the sample'ssample.json file. Think of it as the "cwd" for thefolder 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 specifiessomething 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 orfiles) that are named relative to the"base" property and will beincludedin the sample that is delivered by the various sample browsers. This propertyis required if the"commonFolder" object is present.

NOTE: The folder that contains the core sample source must be explicitlynamed (e.g.,sample-folder-name above), in addition to any files and folderslocated outside of the sample folder. Specifying a folder in the "include"property means that the named folder and all files and folders within thatnamed 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 onefolder, the sample folder.

"exclude":[<array>,<of>,<strings>] represents a list of items (folders orfiles) that are named relative to the"base" property and areexcludedfrom the sample that is delivered by the various sample browsers. Thisproperty 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 afolder or file's presence in the"include" array, the"exclude" array haspriority. Like the"include" property, naming a folder in the"exclude"property means that folder and all sub-folders and files contained within itare excluded.

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

A detailed description of thesample.json attributes can be found on theSample Browser Behavior wiki page.

NOTE: Do not copy and paste thissample.json file into your sampleproject. 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 thesample browser.

A short (one or two sentences) describing your sample, which will be presentedby thesample browser.

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

Seethis sample tree for an example ofhow the"categories" array works.

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

The"toolchain" attribute specifies the compiler to be used to "index" thesample sources for "intellisense" features. In practice, it only has meaningfor C/C++ projects created in Visual Studio or Eclipse. It is not specifyingthe compiler to be used for building the sample project, your build files dothat, it is only used to tell the IDE (VS or Eclipse) which compiler to usefor generating intellisense hints. It has a default value of"gcc" on Linuxand"cl" on Windows, if not specified. See the"toolchain" section of theSample 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 andonly theoneapi-cli and VSCode sample browsers will deliver Fortran andPython samples.

This attribute is recognized by all sample browsers.

The"dependencies" array specifies which tools or "components" are needed tobuild and run your sample. The names of any dependent oneAPI components willmatch their installed directory names (e.g. "mkl", "tbb", "vtune", etc.).

A test is performed by the sample browsers to determine if the requireddependencies have been installed and are present on a user's developmentsystem. If one or more dependencies are found to be missing, an informationalmessage is presented to the user when they are viewing and/or creating asample project based on the sample. Lack of a dependencydoes not prevent aproject from being created, it simply serves as a way to let the user knowthat the new sample project may not build or run correctly until they haveresolved the missing dependencies.

NOTE: The exact name and spelling of oneAPI component dependencies isdetermined by looking at the component folders as they are installed by theoneAPI installer. For the current list of dependency review the componentfolder 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 simplymapped to a directory. But if it is preceded withpkg| then it can name apackage. The full syntax is:

pkg|<package-name>|<url>

where the<url> will be passed to the user in the event the package is notpresent. 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, forexample, ICC or Fortran, it can specify it exactly with thecompiler|dependency declaration. Normally, an entry in the"dependencies" array isexactly matched to a component folder name. But if that name is precededwithcompiler| 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 thedependencies attribute, use dpcpp instead.

compiler|<compiler-name>

Example:

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

See thecompiler| section of theSample Browser Behavior document for more details.

This required attribute is used as a sample filter, not as a requirement ofthe development system. It is intended to describe which hardware devices thesample 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 computedevices, indicate that by including multiple device names in the array.

This optional string can be used to reference a non-default publicly availablereadme file location. Typically this is used when the README.md in the samplerepo 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, thesample aggregator will attempt toautomatically create this attribute by providing a link to a README filelocated in your sample's top-level Git folder.

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

The optional"builder" attribute indicates the preferred builder. Thedefault builder is"cmake" and applies if the the"builder" attribute isnot provided, the content of the "builder" array is not recognized or theconditions 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 arrayelements is important, as the samples browsers will evaluate the list ofprovided builders in the order presented by the array.

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

An"ide" builder value means the sample contains IDE-specific project filesthat 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 inthe root of the sample).

NOTE: Only the Visual Studio sample browser checks for and importsproject and solution files. Neither the Eclipse sample browser nor the VSCodesample browser support importing project files. They will, however, importcmake and make projects.

Specifying"make" means the sample includes aMakefile ormakefile inthe sample's root folder.

NOTE: Makefile samples are not supported on Windows systems, at thistime, due to the difficulty insuring that your makefile will work properlywithnmake on Windows and withmake on Linux and macOS systems.

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

Specifying"cli"anywhere in the "builder" array list makes the samplevisible only in the oneapi-cli tool (the CLI sample browser) and Visual StudioCode; meaning the IDE sample browsers (Visual Studio and Eclipse) will ignorethe 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 theSampleBrowser Behavior wiki page.

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

This attributedoes not impact the compiler that is used to actually buildthe sample, it only impacts the Eclipse indexer (aka "intellisense) featurethat manages how potential C/C++ syntax errors are displayed in the Eclipseedit window.

NOTE: Do not add the"altindex" attribute to yoursample.json fileunless you have been directed to do so by the IDEV team. A request to add thisflag 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 aggregationsystem to uniquely identify your sample. The GUID may be used to enable anddisable samples from tests and/or distribution. The sample author's onlyresponsibility is to assign a GUID to their sample.

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

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

Check theUppercase andHyphens boxes, all others should be cleared.The GUID field in yoursample.json file should have a format similar tothe following:

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

See thesample.json CI Test Object wiki pagefor details.