Skip to content

Latest commit

 

History

History
49 lines (44 loc) · 3.94 KB

contribute_rules.md

File metadata and controls

49 lines (44 loc) · 3.94 KB

Ruiles to Contribute a Compiler Examples

The goal of "Compiler Examples" is to educate novice to intermediate programmers on the use of the ROCm LLVM compiler by clearly showing examples of the LLVM commands used to compile, link, and execute a variety of examples.

Contributors should follow these rules:

  • All examples must be driven by a Makefile whose default target is to compile source.
  • All Makefiles will support targets run, clean, and help.
  • Examples that have a single source should attempt to build executable in a single command that performs compile and link.
  • Examples that have a single source should also build targets '$(TESTNAME).o', obin and run_obin . Showing how to compile and link in two steps.
  • When Makefile is executed all executed commands will clearly be shown.
  • Start each Makefile as follows (adjusted for path to inc directory):
mkfile_dir := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
include $(mkfile_dir)../../inc/find_gpu_and_install_dir.mk
  • Prefix all input files with '$(mkfile_dir)'. This allows examples to be run both in-tree and out-of-tree. Do not use $(mkfile_dir) for any output files.
  • Use these make variables set by the above include
   $(LLVM_INSTALL_DIR)   - location of compiler installation
   $(LLVM_GPU_ARCH)      - GPU architecture.
   $(LLVM_COMPILER_NAME) - AMD, AOMP, or clang

  • The '$(LLVM_COMPILER_NAME)' can be used to differentiate between product rocm compiler, the aomp development compiler, and a trunk compiler.

  • Each example README.md will document the objective, requirements and optional runtime controls (environment variables) even though the printed commands generated by make will clearly show the values set.

  • When example is functional, the contributor will update the category's recursive Makefile AND the category's README.md.

  • No cmake in Compiler examples. UNLESS sources must be obtained from an external repo and those source require cmake.

  • No scripts , the current existing scripts will be reworked into the Makefile and deleted

  • No script to execute all the examples, use make at top level to run all examples recursively.

  • The category "stress" may be renamed to "no-ci". Recursive execution of the stress category is disabled in the top level Makefile so it is not run during continuous integration.

  • All examples should have small execution times, less than 5 seconds. Otherwise, put example in stress category.

  • Single source examples should build the binary in a single compile step.

  • All single source examples should include inc/obin.mk to allow for make obin and make run_obin targets.

  • Revisit Compiler Examples categories. Should we have aomp_fortran aomp_c, and omp_c++?

  • Running with nvidia LLVM_GPU_ARCH such as nv_70 will likely fail with LLVM_INSTALL_DIR=/opt/rocm/lib/llvm. However, setting LLVM_INSTALL_DIR to a trunk built compiler may work if run on a cuda system.

  • multi-arch examples will be confined to stress.

  • How should we identify examples that show nonstandard datatypes like complex, _Float16, bf16, short, and char?

  • We expect to have a python category that will use the compiler to build shared objects for GPU execution used by python.

  • We need to make most examples run with gpurun or optionally be able to turn on or off gpurun. Note that gpurun does not work for nvidia. Maybe we can turn off gpurun in when nvidia LLVM_GPU_ARCH is identfied.

  • If examples have software dependencies other than the compiler install, such as thrust, the Makefile should attempt to test for the dependency and properly fail if it does not exist. See examples in stdpar.

  • All examples should be tested with rocm 6.1 or later compiler

  • All examples should be tested with aomp 17.0-2 or later.

  • All examples should be tested with trunk build of llvm.

  • All examples should be tested with recursive makefile with in-tree sources.

  • All examples should be tested with recursive makefile with out-of-tree sources.