|
| 1 | +# HIPRT |
| 2 | +This is the main repository for the source code for HIPRT. |
| 3 | + |
| 4 | +## Cloning and Building |
| 5 | + |
| 6 | +1. `git clone https://github.com/GPUOpen-LibrariesAndSDKs/HIPRT` |
| 7 | +2. `git submodule update --init --recursive` |
| 8 | +3. `git lfs fetch` (To get resources for running performance tests) |
| 9 | +4. `.\tools\premake5\win\premake5.exe vs2019` |
| 10 | + |
| 11 | +### Using Bitcode |
| 12 | +Add the option `--bitcode` to enable precompiled bitcode. |
| 13 | + |
| 14 | +#### Generation of bitcode |
| 15 | +- After premake, go to `scripts/bitcodes`, then run `python compile.py` which compiles kernels to bitcode and fatbinary. |
| 16 | +- Or pass `--precompile` to premake. it executes the `compile.py` during premake. Note that you cannot do it in git bash on windows (because of hipcc...) |
| 17 | + |
| 18 | + |
| 19 | +## Running Unit Tests |
| 20 | + |
| 21 | +There are three types of tests. |
| 22 | +1. HiprtTests - tests covering all basic features. |
| 23 | +2. ObjTestCases - tests with loading meshes and testing advanced features like shadow/ AO. |
| 24 | +3. PerformanceTestCases - tests with complex mesh to test performance features. |
| 25 | + |
| 26 | +Example: `..\dist\bin\Release\unittest64.exe --width=512 --height=512 --referencePath=.\references\ --gtest_filter=hiprt*:Obj*" ` |
| 27 | + |
| 28 | +## Developing HIPRT |
| 29 | + |
| 30 | +### Compiling Bundled Bitcode and Fatbinary |
| 31 | +- Clone `hipSdk` repo to the root directory. |
| 32 | +- Go to `scripts/bitcodes`, run `python compile.py` which uses `hipcc` from the `hipSdk` directory. (todo. make it more general, maybe search for `hipcc` from path, if it's not found, use the directory above or something like this) |
| 33 | + - Note use python version 3.*+. |
| 34 | + - Git bash shell is not supported for compile.py. |
| 35 | + |
| 36 | +### Coding Guidelines |
| 37 | +- Resolve compiler warnings. |
| 38 | +- Use lower camel case for variable names (e.g., `nodeCount`) and upper camel case for constants (e.g., `LogSize`). |
| 39 | +- Separate functions by one line. |
| 40 | +- Use prefix `m_` for non-static member variables. |
| 41 | +- Do not use static local variables. |
| 42 | +- Do not use `void` for functions without arguments (leave it blank). |
| 43 | +- Do not use blocks without any reason. |
| 44 | +- Use references instead of pointers if possible. |
| 45 | +- Use bit-fields instead of explicit bit masking if possible. |
| 46 | +- Use `nullptr` instead of `NULL` or zero. |
| 47 | +- Use C++-style casts (e.g., `static_cast`) instead of C-style cast. |
| 48 | +- Add `const` for references and pointers if they are not being changed. |
| 49 | +- Add `constexpr` for variables and functions if they can be constant in compile time (do not use `#define` if possible). |
| 50 | +- Use `if constsexpr` instead of `#ifdef` if possible. |
| 51 | +- Throw `std::runtime_error` with an appropriate message in case of failure in the core and catch it in `hiprt.cpp`. |
| 52 | + |
| 53 | +#### String |
| 54 | +- Use `std::string` instead of C strings (i.e., `char*`) and avoid C string functions as much as possible. |
| 55 | +- Use `std::cout` and `std::cerr` instead of `printf`. |
| 56 | +- Do not assign `char8_t` (or `std::u8string`) to `char` (or `std::string`). They will not be compatible in C++20. |
| 57 | + |
| 58 | +#### File |
| 59 | +- Use `std::ifstream` and `std::ofstream` instead of `FILE`. |
| 60 | +- Use `std::filesystem::path` for files and paths instead of `std::string`. |
| 61 | + |
| 62 | +#### Class |
| 63 | +- Use the in-class initializer instead of the default constructor. |
| 64 | +- Use the keyword `override` instead of `virtual` (or nothing) when overriding a virtual function from the base class. |
| 65 | + - Reason: The `override` keyword can help prevent bugs by producing compilation errors when the intended override is not actually implemented as an override. For example, when the function type is not exactly identical to the base class function. This can be caused by mistakes or if the virtual functions in the base class are changed due to refactor. |
| 66 | +- Use `std::optional` instead of pointers for optional parameters. |
| 67 | + - Reason: `std::optional` guarantees that no auxiliary memory allocation is needed. Meaning, it does not involve dynamic memory allocation & deallocation on the heap, which results in better performance and less memory overhead. |
| 68 | +- A base class destructor should be either public and virtual, or protected and non-virtual |
| 69 | + - Reason: This is to prevent undefined behavior. If the destructor is public, then the calling code can attempt to destroy a derived class object/instance through a base class pointer, and the result is undefined if the base class’s destructor is non-virtual. |
| 70 | +- Implement the customized {copy/move} {constructor/assignment operator} if an user-defined destructor of a class is needed, or remove them using `= delete` |
| 71 | + - Reason: [Rule of five](https://en.cppreference.com/w/cpp/language/rule_of_three) |
| 72 | + |
| 73 | +### Versioning |
| 74 | +- When we update the master branch, we need to update the version number of hiprt in `version.txt`. |
| 75 | +- If there is a change in the API, you need to update minor version. |
| 76 | +- If the major and minor versions matches, the binaries are compatible. |
| 77 | +- Each commit in the master should have a unique patch version. |
0 commit comments