
Packages:
---------
    This package contains "AMD Optimizing C/C++ and Fortran Compilers" - abbreviated as AOCC

Installation steps:
-------------------
    TAR:
        Download aocc-compiler-<version>.tar to the directory of your choice, say <compdir>
        Installation with tar file does not require root or sudo permission

        $ cd <compdir>
        $ tar -xvf aocc-compiler-<version>.tar
        $ cd aocc-compiler-<version>
        $ bash install.sh
            . This will install the compiler and display the AOCC setup instructions

        $ source <compdir>/setenv_AOCC.sh
            . This will set up a shell environment for using AOCC C, C++, and Fortran compilers in the shell environment, where the above command was executed.

    RPM:
        aocc-compiler-<version>-1.x86_64.rpm for RHEL
        aocc-compiler-<version>.sles15-1.x86_64.rpm for SLES

        Download the rpm file to directory of your choice, say <compdir>
        You need to be root or have sudo access for installing a rpm file.

        $ cd <compdir>
        $ sudo rpm -ivh <aocc rpm file>
            . This will install the compiler under /opt/AMD/aocc-compiler-<version> on RHEL
            . This will install the compiler under /opt/AMD/aocc-compiler-<version>.sles15 on SLES

        $ source /opt/AMD/aocc-compiler-<version>/setenv_AOCC.sh on RHEL
        $ source /opt/AMD/aocc-compiler-<version>.sles15/setenv_AOCC.sh on SLES

            . This will set up a shell environment for using AOCC C, C++, and Fortran compilers in the shell environment, where the above command was executed.

    DEB:
        Download aocc-compiler-<version>_1_amd64.deb to directory of your choice say <compdir>
        You need to be root or have sudo access for installing a deb file

         $ cd <compdir>
         $ dpkg -i aocc-compiler-<version>_1_amd64.deb
            . This will install the compiler under /opt/AMD/aocc-compiler-<version>

         $ source /opt/AMD/aocc-compiler-<version>/setenv_AOCC.sh
            . This will set up a shell environment for using AOCC C, C++, and Fortran compilers in the shell environment, where the above command was executed.

    Notes:
        Once you have setup AOCC environment by executing 'source' command mentioned above, you can check the version of compiler using command 'clang -v'


Using the compiler:
-------------------

Once you have setup AOCC environment in your shell by executing 'source' command in above section, you can use clang, clang++, and flang for C, C++, and Fortran code respectively.

    For C compiler:
        $ clang [command line flags] xyz.c -o xyz.out
        $ ./xyz.out

    For C++ compiler:
        $ clang++ [command line flags] xyz.cpp -o xyz.out
        $ ./xyz.out

    For Fortran compiler:
        $ flang [command line flags] xyz.f90 -o xyz.out
        $ ./xyz.out

    Some applications may benefit from optimized libraries. AOCC is known to work seamlessly with these libraries.
    It is recommended that you evaluate these libraries while building your application with AOCC as
    they may help boost the performance of your application over and above the compiler optimizations that come with AOCC.

    In most cases these libraries only need to be linked.
    Example:
        $ export LD_LIBRARY_PATH=<compdir>/aocc-compiler-<version>/lib:$LD_LIBRARY_PATH
        $ clang [command line flags] xyz.c -L<compdir>/aocc-compiler-<version>/lib -lamdlibm -o xyz.out
        $ ./xyz.out

    The AOCC installation includes OpenMP specific debugging support (OMPD) for debugging C/C++ OpenMP programs through a gdb plugin.
    NOTES:
        (1) Debugging code that runs on an offloading device is not supported yet.
        (2) The OMPD plugin requires an environment with Python version 3.5 or above. The gdb that is used with the OMPD plugin also needs to be based on Python version 3.5 or above.

    Instructions to use OpenMP specific debugging support for debugging C/C++ OpenMP programs through the gdb plugin are as follows:

    Add folders ompd and lib to your LD_LIBRARY_PATH
        $ export LD_LIBRARY_PATH=<compdir>/aocc-compiler-<version>/ompd:<compdir>/aocc-compiler-<version>/lib:$LD_LIBRARY_PATH

    Set OMP_DEBUG to enabled
        $ export OMP_DEBUG=enabled

    Compile the program to be debugged with '-g' and '-fopenmp' options as shown for a sample C source file xyz.c
        $ <compdir>/aocc-compiler-<version>/bin/clang -g -fopenmp xyz.c -o xyz.out

        NOTE:
        The program to be debugged needs to have a dynamic link dependency on 'libomp.so' under <compdir>/aocc-compiler-<version>/lib for OpenMP-specific debugging to work correctly.
        The user can check this using ldd on the generated binary i.e. xyz.out

        Debug the binary xyz.out by invoking gdb with the plugin as shown below. Please note that plugin '<compdir>/aocc-compiler-<version>/ompd/__init__.py' should be used.
            $ gdb -x <compdir>/aocc-compiler-<version>/ompd/__init__.py ./xyz.out

            - The gdb command 'help ompd' lists the subcommands available for OpenMP-specific debugging.
            - The command 'ompd init' needs to be run first to load the libompd.so available in the $LD_LIBRARY_PATH environment variable, and to initialize the OMPD library.
            - The 'ompd init' command starts the program run, and the program stops at a temporary breakpoint at the OpenMP internal location ompd_dll_locations_valid().
            - The user can 'continue' from the temporary breakpoint for further debugging.
            - The user may place breakpoints at the OpenMP internal locations 'ompd_bp_thread_begin' and 'ompd_bp_thread_end' to catch the OpenMP thread begin and thread end events.
            - Similarly, 'ompd_bp_task_begin' and 'ompd_bp_task_end' breakpoints may be used to catch the OpenMP task begin and task end events; 'ompd_bp_parallel_begin' and 'ompd_bp_parallel_end' to catch OpenMP parallel begin and parallel end events.

        List of OMPD subcommands that can be used in GDB:
            - ompd init     -- Find and initialize OMPD library.
            - ompd bt       -- Turn filter for "bt" output on or off. Specify the "on continued" option to trace worker threads back to master threads.
            - ompd icvs     -- Display the values of the Internal Control Variables.
            - ompd parallel -- Display the details of the current and enclosing parallel regions.
            - ompd step     -- Execute "step" and skip runtime frames as much as possible.
            - ompd threads  -- Provide information on threads of current context.


Licensing Information:
----------------------
The component and its associated license

Component          License
---------          --------
AMDALLOC           aocc-compiler-<version>/AMDALLOC-LICENSE.TXT

