README.rst

..
  SPDX-FileCopyrightText: Copyright 2024, 2025 Arm Limited and/or its affiliates <open-source-office@arm.com>
  SPDX-License-Identifier: BSD-3-Clause-Clear

This repository hosts various code examples for learning.

Learning paths code examples
============================

Code examples from learning paths are stored in ``learning-paths/``, with a
directory structure that mimics the one from the learning path.

.. list-table:: Learning paths code examples
   :header-rows: 1

   * - Learning path
     - Sample code directory

   * - `Accelerate Matrix Multiplication Performance with SME2 <https://learn.arm.com/learning-paths/cross-platform/multiplying-matrices-with-sme2>`_
     - `learning-paths/cross-platform/multiplying-matrices-with-sme2 <https://gitlab.arm.com/learning-code-examples/code-examples/-/blob/main/learning-paths/cross-platform/multiplying-matrices-with-sme2>`_

   * - `Develop a native C++ library on an Arm-based machine <https://learn.arm.com/learning-paths/cross-platform/matrix/>`_
     - `learning-paths/cross-platform/matrix <https://gitlab.arm.com/learning-code-examples/code-examples/-/blob/main/learning-paths/cross-platform/matrix>`_

Adding new code examples
========================

This repository is a collection of random and unrelated code examples, which
means this repository could quickly become a nightmare to manage. In order to
ease its management, please follow those steps when adding new code examples:

1. place your learning paths' code examples in the ``learning-paths/``
   directory, mirroring the path used on ``https://learn.arm.com/``
2. Ensure that your code examples have a README file, and that this README file
   refers to your learning path on ``https://learn.arm.com/``.
3. Ensure that your code examples are under the BSD-3-Clause-Clear license and
   that a copy of the LICENSE.txt is at the roor of your code examples.
4. Ensure that all your source code files have been annotated with the proper
   ``SPDX-FileCopyrightText`` and ``SPDX-License-Identifier`` ``SPDX`` tags.
5. Update the ``Learning path code examples`` table in the above section
   with the new learning path and code examples directory.

There is a ``utils/check.py`` utility to automate the checking of steps 3 and 4.
Step 2 is only checked for the presence of a README file.

Example:

.. code-block:: bash

  $ utils/check.py learning-paths/cross-platform/multiplying-matrices-with-sme2
  Code examples directory 'learning-paths/cross-platform/multiplying-matrices-with-sme2' passed all checks !

Your learning path should refer to your code examples by using the URL that is
corresponding to the download of your directory. The URL is looking like
``https://gitlab.arm.com/learning-code-examples/code-examples/-/archive/main/code-examples-main.tar.gz?path=learning-paths/cross-platform/multiplying-matrices-with-sme2``.
This ensures users are *only* downloading the code examples of the learning
path they are currently working on rather than downloading the full repository.
This is also the reason why a copy of the LICENSE.txt file should be placed at
the root of your code examples --- because users will only download a partial
view of the repository.

License
=======

learning-code-examples/code-examples is distributed under the `Clear BSD License
<https://gitlab.arm.com/learning-code-examples/code-examples/-/blob/main/README.rst>`_.

Security
========

To report security vulnerabilities in this project, follow the guidance in the
`security policy <SECURITY.rst>`_.

Feedback, contributions and support
===================================

Please use the issue tracker associated with this repository for feedback.

Code contributions are most welcomed. Please make sure they stick to the style
used in the rest of code and submit them via gitlab merge requests.