added Getting ROCm Source Files (#2952)

* added Accessing ROCm Source Files * changed per comments * Update README.md implement dgaliffi suggestions Co-authored-by: David Galiffi <dgaliffi@amd.com> * Update README.md implement dgailifi suggestion Co-authored-by: David Galiffi <dgaliffi@amd.com> * Update README.md implement dgailifi suggestion Co-authored-by: David Galiffi <dgaliffi@amd.com> * Update README.md implement dgailifi suggestion Co-authored-by: David Galiffi <dgaliffi@amd.com> * add default.xml link * update README --------- Co-authored-by: David Galiffi <dgaliffi@amd.com>
2026-01-08 22:28:06 -05:00 · 2024-03-07 14:41:39 -08:00
parent 7b3253a42f
commit 47192a92ba
2 changed files with 54 additions and 24 deletions
--- a/README.md
+++ b/README.md
@@ -19,6 +19,49 @@ ROCm supports programming models, such as OpenMP and OpenCL, and includes all ne
 source software compilers, debuggers, and libraries. ROCm is fully integrated into machine learning
 (ML) frameworks, such as PyTorch and TensorFlow.

+## Getting the ROCm Source Code
+
+AMD ROCm is built from open source software. It is, therefore, possible to modify the various components of ROCm by downloading the source code and rebuilding the components. The source code for ROCm components can be cloned from each of the GitHub repositories using git.  For easy access to download the correct versions of each of these tools, the ROCm repository contains a repo manifest file called [default.xml](./default.xml). You can use this manifest file to download the source code for ROCm software.
+
+### Installing the repo tool
+
+The repo tool from Google allows you to manage multiple git repositories simultaneously. Run the following commands to install the repo tool:
+
+```bash
+mkdir -p ~/bin/
+curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
+chmod a+x ~/bin/repo
+```
+
+**Note:** The ```~/bin/``` folder is used as an example. You can specify a different folder to install the repo tool into if you desire.
+
+### Installing git-lfs
+
+Some ROCm projects use the Git Large File Storage (LFS) format that may require you to install git-lfs. Refer to [Git Large File Storage](https://github.com/git-lfs/git-lfs/blob/main/INSTALLING.md) for more information. For example, to install git-lfs for Ubuntu, use the following command:
+
+```bash
+sudo apt-get install git-lfs
+```
+
+### Downloading the ROCm source code
+
+The following example shows how to use the repo tool to download the ROCm source code. If you choose a directory other than ~/bin/ to install the repo tool, you must use that chosen directory in the code as shown below:
+
+```bash
+mkdir -p ~/ROCm/
+cd ~/ROCm/
+~/bin/repo init -u http://github.com/ROCm/ROCm.git -b roc-6.0.x
+~/bin/repo sync
+```
+
+**Note:** Using this sample code will cause the repo tool to download the open source code associated with the specified ROCm release. Ensure that you have ssh-keys configured on your machine for your GitHub ID prior to the download as explained at [Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
+
+### Building the ROCm source code
+
+Each ROCm component repository contains directions for building that component, such as the rocSPARSE documentation [Installation and Building for Linux](https://rocm.docs.amd.com/projects/rocSPARSE/en/latest/Linux_Install_Guide.html). Refer to the specific component documentation for instructions on building the repository.
+
+Each release of the ROCm software supports specific hardware and software configurations. Refer to [System requirements (Linux)](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html) for the current supported hardware and OS.
+
 ## ROCm documentation

 This repository contains the [manifest file](https://gerrit.googlesource.com/git-repo/+/HEAD/docs/manifest-format.md)
@@ -32,16 +75,14 @@ Source code for our documentation is located in the `/docs` folder of most ROCm

 The ROCm documentation homepage is [rocm.docs.amd.com](https://rocm.docs.amd.com).

-### Building our documentation
+### Building the documentation

 For a quick-start build, use the following code. For more options and detail, refer to
 [Building documentation](./docs/contribute/building.md).

 ```bash
 cd docs
-
 pip3 install -r sphinx/requirements.txt
-
 python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
 ```

@@ -49,7 +90,6 @@ Alternatively, CMake build is supported.

 ```bash
 cmake -B build
-
 cmake --build build --target=doc
 ```

--- a/docs/contribute/contributing.md
+++ b/docs/contribute/contributing.md
@@ -36,7 +36,7 @@ To make edits to our documentation via PR, follow these steps:
      git clone git@github.com:ROCm/ROCm.git
      ```

-   * Add your fork to this local copy of the repository. Run:
+   * Optionally add your fork to this local copy of the repository by running:

      ```bash
      git add remote <name-of-my-fork> <git@github.com:my-username/ROCm.git>
@@ -45,43 +45,33 @@ To make edits to our documentation via PR, follow these steps:
      To get the URL of your fork, go to your GitHub profile, select the fork and click the green 'Code'
      button (the same process you followed to get the main GitHub repository URL).

-4. Check out the **develop** branch and run 'git pull' (and/or 'git pull origin develop' to ensure your
-  local version has the most recent content.
+4. Change directory into your local copy of the repository, and run ``git pull`` (or ``git pull origin develop``) to ensure your local copy has the most recent content.

-5. Create a new branch.
+5. Create and checkout a new branch using the following command:

    ```bash
-    git checkout -b my-new-branch
+    git checkout -b <branch_name>
    ```

-6. Make your changes locally using your preferred code editor. Follow the guidelines listed on the
+6. Change directory into the `./docs` folder and make any documentation changes locally using your preferred code editor. Follow the guidelines listed on the
   [documentation structure](./doc-structure.md) page.

-7. (optional) We recommend running a local test build to ensure the content looks the way you expect.
-
-    In your terminal, run the following commands from within your cloned repository:
+7. Optionally run a local test build of the documentation to ensure the content builds and looks as expected. In your terminal, run the following commands from within the `./docs` folder of your cloned repository:

     ```bash
-     cd docs/   # The other commands are run from within the ./docs folder
-     
     pip3 install -r sphinx/requirements.txt  # You only need to run this command once
-     
     python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
     ```

-    The build files are located in the `docs/_build` folder. To preview your build, open the index file
-    (`docs/_build/html/index.html`) file. For more information, see
-    [Building documentation](building.md). To learn
-    more about our build tools, see
-    [Documentation toolchain](toolchain.md).
+    The build output files are located in the `docs/_build` folder. To preview your build, open the index file
+    (`docs/_build/html/index.html`) file. For more information, see [Building documentation](building.md). To learn
+    more about our build tools, see [Documentation toolchain](toolchain.md).

-8. Commit your changes and push them to GitHub. Run:
+8. Commit your changes and push them to GitHub by running:

    ```bash
    git add <path-to-my-modified-file> # To add all modified files, you can use: git add .
-
    git commit -m "my-updates"
-
    git push <name-of-my-fork>
    ```