1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
.. meta::
:description: How to build and install rocSPARSE on Windows
:keywords: rocSPARSE, ROCm, API, documentation, installation, Windows, build
.. _windows-install:
********************************************************************
Installing and building rocSPARSE for Windows
********************************************************************
This topic describes how to install or build rocSPARSE on Windows by using prebuilt packages or building from source.
Prerequisites
=============
rocSPARSE on Windows requires an AMD HIP SDK enabled platform. It's supported on the
same Windows versions and toolchains that the HIP SDK supports. For more information, see
:doc:`HIP SDK installation for Windows <rocm-install-on-windows:index>`.
Installing prebuilt packages
============================
rocSPARSE can be installed on Windows 10 or 11 using the AMD HIP SDK installer.
The simplest way to add rocSPARSE to your code is to use CMake.
Add the SDK installation location to your ``CMAKE_PREFIX_PATH``.
.. note::
You must use quotes because the path contains a space.
.. code-block:: shell
-DCMAKE_PREFIX_PATH="C:\Program Files\AMD\ROCm\5.5"
In your ``CMakeLists.txt`` file, use these lines:
.. code-block:: shell
find_package(rocsparse)
target_link_libraries( your_exe PRIVATE roc::rocsparse )
After rocSPARSE is installed, it can be used just like any other library with a C API.
To call rocSPARSE, the ``rocsparse.h`` header file must be included in the user code.
This means the rocSPARSE import library and dynamic link library respectively become link-time and run-time dependencies
for the user application.
After the installation, you can find ``rocsparse.h`` in the HIP SDK ``\\include\\rocsparse``
directory. When you need to include rocSPARSE in your application code, you must only use these two files.
You can find the other rocSPARSE files included in the HIP SDK ``\\include\\rocsparse\\internal`` directory, but
do not include these files directly in your source code.
Building rocSPARSE from source
=================================
It isn't necessary to build rocSPARSE from source because it's ready to use after installing
the prebuilt packages, as described above.
To build rocSPARSE from source, follow the instructions in this section.
Requirements
------------
To compile and run rocSPARSE, the `AMD ROCm Platform <https://github.com/ROCm/ROCm>`_ is required.
Building rocSPARSE from source also requires the following components and dependencies:
* `git <https://git-scm.com/>`_
* `CMake <https://cmake.org/>`_ (Version 3.5 or later)
* `rocPRIM <https://github.com/ROCm/rocPRIM>`_
* `rocBLAS <https://github.com/ROCm/rocBLAS>`_ (Optional: for the library)
* `vcpkg <https://github.com/Microsoft/vcpkg.git>`_
* `GoogleTest <https://github.com/google/googletest>`_ (Optional: only required to build the clients)
* `Python <https://www.python.org/>`_
* `PyYAML <https://pypi.org/project/PyYAML/>`_
When building rocSPARSE from source, select supported versions of the math library
dependencies (:doc:`rocPRIM <rocprim:index>` and optionally :doc:`rocBLAS <rocblas:index>`). Given a version of rocSPARSE,
you must use a version of rocPRIM (and optionally rocBLAS) that is the same or later. For example, it's
possible to build rocSPARSE 3.2.0 with any future rocPRIM 3.Y.Z version (with the same major version
and where 3.Y.Z is 3.2.0 or later), but compiling rocSPARSE with an older version of
rocPRIM, such as 3.1.0, is not supported.
Downloading rocSPARSE
----------------------
The rocSPARSE source code for Windows, which is the same as for Linux, is available
at the `rocSPARSE GitHub <https://github.com/ROCm/rocSPARSE>`_.
The ROCm HIP SDK version might be shown in the default installation path, but
you can run the HIP SDK compiler from the ``bin/`` folder to display the version using this command:
.. code-block:: shell
hipcc --version
The HIP version has major, minor, and patch fields, possibly followed by a build specific identifier.
For example, the HIP version might be ``5.4.22880-135e1ab4``.
This corresponds to major release ``5``, minor release ``4``, patch ``22880``, and build identifier ``135e1ab4``.
The rocSPARSE GitHub includes branches with names like ``release/rocm-rel-major.minor``,
where major and minor have the same meaning as the HIP version.
For example, use the following command to download rocSPARSE:
.. code-block:: shell
git clone -b release/rocm-rel-x.y https://github.com/ROCm/rocSPARSE.git
cd rocSPARSE
Replace ``x.y`` in the above command with the version of HIP SDK installed on your machine.
For example, if you have HIP 5.5 installed, use ``-b release/rocm-rel-5.5``.
Add the SDK tools to your path with an entry like the following:
.. code-block:: shell
%HIP_PATH%\bin
Building using make
--------------------
This section describes the steps required to build rocSPARSE using the ``rmake.py`` script. You can build:
* The library
* The library and client
To call rocSPARSE from your code, you only need the library. The client contains testing and benchmark tools.
``rmake.py`` prints the full ``cmake`` command being used to configure rocSPARSE based on the ``rmake`` command line options.
This full ``cmake`` command can be used in your own build scripts to bypass the Python helper script for a fixed set of build options.
Building the library from source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following table lists the common ways to use ``rmake.py`` to build the rocSPARSE library only.
.. csv-table::
:header: "Command","Description"
:widths: 40, 90
"``./rmake.py -h``","Print the help information."
"``./rmake.py``","Build the library."
"``./rmake.py -i``","Build the library, then build and install the rocSPARSE package. To keep rocSPARSE in your local tree, do not use the ``-i`` flag."
"``./rmake.py -in``","Build the library without rocBLAS, then build and install the rocSPARSE package. To keep rocSPARSE in your local tree, do not use the ``-i`` flag."
"``./rmake.py -i -a gfx900``","Build the library using only the gfx900 architecture, then build and install the rocSPARSE package. To keep rocSPARSE in your local tree, do not use the ``-i`` flag."
Building the library and client from source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The client executables (``.exe`` files) are listed in the table below:
.. csv-table::
:header: "Executable name","Description"
:widths: 40, 90
"rocsparse-test","Runs Google Tests to test the library"
"rocsparse-bench","An executable to benchmark and test functions"
"rocsparse_axpyi","Example C code that calls the ``rocsparse_axpyi`` function"
The following table lists the common ways to use ``rmake.py`` to build the rocSPARSE library and client.
.. csv-table::
:header: "Command","Description"
:widths: 40, 90
"``./rmake.py -h``","Print the help information."
"``./rmake.py -c``","Build the library and client in your local directory."
"``./rmake.py -ic``","Build and install the rocSPARSE package and build the client. To keep rocSPARSE in your local directory, do not use the ``-i`` flag."
"``./rmake.py -icn``","Build and install the rocSPARSE package without rocBLAS and build the client. To keep rocSPARSE in your local tree, do not use the ``-i`` flag."
"``./rmake.py -ic -a gfx900``","Build and install the rocSPARSE package using only the gfx900 architecture and build the client. To keep rocSPARSE in your local tree, do not use the ``-i`` flag."
|
