DOCSEARCHbyAlgolia
Submit Docs

OpenMP Examples

repository·main·Indexed 42 days ago

https://github.com/openmp/examples

A collection of practical examples for using the OpenMP API, provided in LaTeX format. Includes source code for C, C++, and Fortran across various chapters such as SIMD, tasking, and synchronization, along with tools like eval_codes for compilation testing and check_tags for metadata validation.

Tokens
3.9K
Snippets
12
Records
19
Agent score
54%

What's inside OpenMP Examples

  1. Git procedure for contributing

    main

    Follow these steps to manage your development environment and branches:

    1. Fork and Clone: Fork the examples-internal repo and clone it locally.
    2. Branching Strategy:
      • For generic or old-version updates: Create a branch off main.
      • For release candidate examples (version #.#): Create a branch off work_#.#.
    3. Workflow:
      • git clone --branch <main|work_#.#> https://github.com/<my_account>/examples-internal
      • git checkout -b <branch_name>
      • Perform add and commit operations.
      • git push -u origin <branch_name>
    4. Building Documentation:
      • Use make to create a full-document PDF.
      • Use make diff to create a PDF showing only the differences.
    5. Submission:
      • Submit an issue (ideally including a diff PDF) before submitting a pull request.
    git clone --branch <main|work_#.#> https://github.com/<my_account>/examples-internal
git checkout -b <branch_name>
# ... add and commit ...
git push -u origin <branch_name>
make
# or
make diff

  2. Submit a contribution to OpenMP Examples

    main

    To add new examples, make changes, or provide corrections, follow this general workflow:

    1. Discussion: Submit an issue on the examples-internal repo for initial evaluation. For new examples, consensus is required at an OpenMP Language Committee meeting before a pull request is requested.
    2. Direct Corrections: If the contribution is an obvious correction, clarification, or note, you may submit a pull request directly.
    3. Approval: Once an issue is discussed and approved, you will be asked to submit a pull request.
    4. Review: Pull requests are reviewed and voted on; changes may be requested before merging into main or a specific working branch.

  3. Process for adding text descriptions

    main

    Text descriptions are written in LaTeX and organized by chapter/section structure:

    • Updating existing text: Edit the description file located at <chap_directory>/<ename>.tex.
    • Adding a Subsection: Include the new content in the appropriate <subsection>.tex file.
    • Adding a Section:
      1. Create a new <section>.tex file.
      2. Add an entry for it in the corresponding chapter file (e.g., Chap_affinity.tex).
    • Adding a Chapter:
      1. Create a Chap_<chap_name>.tex file containing introductory text.
      2. Create a new <section>.tex file with text and links to the code.
      3. Update the Makefile and openmp-examples.tex to include the new chapter file.

    After committing changes to your fork, submit an issue at the OpenMP Examples internal repo including a PDF of the changes.

  4. Locate OpenMP example source code

    main

    The source code for OpenMP examples is organized by chapter. You can find the implementation files in the sources directory located under each specific chapter directory.

    Available chapter directories include:

    • SIMD/sources
    • affinity/sources
    • data_environment/sources
    • devices/sources
    • directives/sources
    • loop_transformations/sources
    • memory_model/sources
    • ompt_interface/sources
    • parallel_execution/sources
    • program_control/sources
    • synchronization/sources
    • tasking/sources

  5. Validate and fix tags with chk_tags.x

    main

    Use chk_tags.x to verify the validity of @@<tags> within source code files. The utility can identify issues and, when used with the -fix flag, attempt to apply fixes by creating a new file named <filename>_fix.

    This tool is primarily used by the ../sources/check_tags script to ensure tag consistency.

    # Basic usage to check files
./chk_tags.x filename1.cpp filename2.cpp

# Strictly check for the "@@<tag>:" format
./chk_tags.x -sc filename.cpp

# Apply fixes to a new file
./chk_tags.x -fix filename.cpp

# List tags found in the files
./chk_tags.x -list filename.cpp

  6. Run a quick compilation test with eval_codes

    main

    The eval_codes script performs a quick compilation test of all example codes.

    Usage Notes:

    • The script attempts to automatically detect your compiler.
    • If automatic detection fails, you can manually specify the compiler by setting the comp_c and comp_cc environment variables.
    • Warning: This script is for reference purposes only and is NOT intended to validate the OpenMP compliance of a compiler.
    • Test results are written to eval_codes.log.
    # If automatic detection fails, set compiler variables manually
export comp_c=gcc
export comp_cc=g++
./eval_codes

  8. Set up the environment with sourceme

    main

    The sourceme file prepares your environment for working with the examples. Running it performs the following actions:

    • Adds eval_codes to your PATH.
    • Creates a tc alias.
    • Defines the OMP_BASE_DI environment variable.
    . sourceme

  9. Generate source templates with get_tags

    main

    The gen_tags utility generates source templates containing proper source tags. It can be used to create new files, add tags to existing files, or print tags from files that already contain them.

    If a filename is not provided, the tool constructs one from the provided name and type. If no tags are provided via CLI, the tool will prompt for tag information interactively.

    # List all supported tags and their valid values
gen_tags -tags

# Create a new file with specific tags
# Filename format: <name.seqno.ext>
gen_tags -<tag_name> <value> my_file.seq01.cpp

# Add tags to an existing file
gen_tags my_existing_file.cpp

  10. List tag information with list_tags

    main

    Use list_tags to extract and display tag information from source files. This is commonly used by the top-level make process to generate generated-include.tex.

    Supported output formats include CSV and LaTeX-compatible version tag info.

    # List tags in CSV format
list_tags -list file1.cpp file2.cpp

# Create version tag info for LaTeX files
list_tags -vtag file1.cpp

# Check line length (default is 75)
list_tags -clen=80 file1.cpp

# Print environment tag values
list_tags -env file1.cpp

  11. Define language-dependent text with h-rules

    main

    To specify text that should only appear for certain languages (e.g., C++ specific notes), use structured environments. The \begin{...} ... \end{...} approach is preferred over unstructured start/end macros.

    Environments

    • \begin{cspecific}[s] ... \end{cspecific} (C)
    • \begin{cppspecific}[s] ... \end{cppspecific} (C++)
    • \begin{ccppspecific}[s] ... \end{ccppspecific} (C/C++)
    • \begin{fortranspecific}[s] ... \end{fortranspecific} (Fortran)

    The [s] option allows specifying a vertical shift for the beginning rule, useful when followed by a section header.

    Unstructured Macros

    • \cspecificstart, \cspecificend (and corresponding versions for cpp, ccpp, fortran)

    Page Markers

    • \topmarker{Lang}: Places a dashed blue line floater at the top of the page for "Lang (cont.)". Valid Lang values are C/C++, C++, or Fortran.
    This text is only for C++ users.
\end{cppspecific}
\topmarker{C++}

  12. Manage chapters and deprecation tables in LaTeX

    main

    Use these macros for high-level document structure and managing feature updates/deprecations:

    Chapter Management

    • \cchapter{<Chapter Name>}{<chap_directory>}: Starts a chapter with correct page spacing.
      • All section/subsection files must be in <chap_directory>.
      • Example sources must be in <chap_directory>/sources.
      • Note: Do not use \sinput{<section_file>}. Use \input{<chap_directory>/<section_file>} instead.

    Deprecation and Update Tables

    • \hexentry[ext1]{<example_name>}[ext2]{<earlier_tag>}: Simplifies entries for feature deprecation. ext1 defaults to c. Use ext2 for a second associated file extension.
    • \hexmentry[ext1]{<example_name>}[ext2]{<earlier_tag>}{<prior_name>}: Used if the example name changed between versions.

    Repository Referencing

    • \examplesref{<verno>}: Reference a specific version of the examples.
    • \examplesblob{<verno/file>}: Reference a specific file in the GitHub Examples repository.
    \hexentry[c]{parallel_for}{1.5}