Merge branch 'master' into feat/version

website/docs/lang/articles/basic/type.md

@@ -99,10 +99,33 @@ As a rule of thumb, implicit type casting is a major source of bugs. And Taichi
 
 #### Implicit type casting in binary operations
 
-Taichi follows the [implicit conversion rules](https://en.cppreference.com/w/c/language/conversion) for the C programming language and implicitly casts operands in a [binary operation](https://en.wikipedia.org/wiki/Binary_operation) into a *common type* if the operation involves different data types. Following are two most straightforward rules for determining the common type in a binary operation:
+Taichi implements its own implicit type casting rules for binary operations, which are slightly different from [those for the C programming language](https://en.cppreference.com/w/c/language/conversion).
 
-- `i32 + f32 = f32` (`int` + `float` = `float`)
-- `i32 + i64 = i64` (low precision bits + high precision bits = high precision bits)
+In general we have three rules with descending priority:
+
+1. integral OP floating_point -> floating_point
+- `i32 + f32 -> f32`
+- `i16 + f16 -> f16`
+
+2. low_precision_bits OP high_precision_bits -> high_precision_bits
+- `i16 + i32 -> i32`
+- `u8 + u16 -> u16`
+
+3. signed OP unsigned -> unsigned
+- `u32 + i32 -> u32`
+- `u8 + i8 -> u8`
+
+For conflicting rules, only the highest priority one will be applied.
+- `u8 + i16 -> i16` (rule #2 conflicts with rule #3: apply rule #2)
+- `f16 + i32 -> f16` (rule #1 conflicts with rule #2: apply rule #1)
+
+A few exceptions:
+1. bit-shift operations: always follow lhs's dtype
+- `u8 << i32 -> u8`
+- `i16 << i8 -> i16`
+
+2. logical operations: always return i32
+3. comparison operations: always return i32
 
 #### Implicit type casting in assignments
 

website/docs/lang/articles/contribution/contributor_guide.md

@@ -102,7 +102,7 @@ We highly recommend that you complete code style checks and integration tests on
 
 ### Enforce code style
 
-Taichi enfoces code style via [pre-commit](https://pre-commit.com/) hooks, which includes the following checks:
+Taichi enforces code style via [pre-commit](https://pre-commit.com/) hooks, which includes the following checks:
 
 1. C++ codes are formatted by `clang-format-10`.
 2. Python codes are formatted by `yapf v0.31.0` based on PEP 8 rules.
@@ -293,6 +293,63 @@ Here, we do not want to repeat some best practices summarized in the following G
   - [Code Health: Respectful Reviews == Useful Reviews](https://testing.googleblog.com/2019/11/code-health-respectful-reviews-useful.html)
   - [How to have your PR merged quickly](https://testing.googleblog.com/2017/06/code-health-too-many-comments-on-your.html)
 
+## Compilation Warnings
+Taichi enforces warning-free codes by turning on `-Werror` (treat warning as error) by default. It is highly recommended to resolve a warning as soon as it raises.
+
+On the other hand, real world issues could be way more complicated than what the compiler expected. So we prepared the following HOWTOs to help resolve some common problems. You are also more than welcome to open up an issue or consult the reviewer inplace for further discussions.
+
+### How to deal with warnings from third-party header files
+There is little we can do about third-party warnings other than simply turning them off.
+
+To mute warnings from specific third-party header files, you can apply `SYSTEM` option when including third-party directories in CMakeFiles. The following example can be found in [cmake/TaichiCore.cmake](https://github.com/taichi-dev/taichi/blob/master/cmake/TaichiCore.cmake):
+```
+# Treat files under "external/Vulkan-Headers/include" as system headers, warnings of which will be muted.
+include_directories(SYSTEM external/Vulkan-Headers/include)
+
+# Treat files under "external/VulkanMemoryAllocator/include" as system headers for target "${CORE_LIBRARY_NAME}"
+target_include_directories(${CORE_LIBRARY_NAME} SYSTEM PRIVATE external/VulkanMemoryAllocator/include)
+```
+
+### How to deal with warnings raised when compiling third-party libraries or targets
+Ideally, third-party submodules should be built completely independent of Taichi project except for the topological dependency. Unfortunately, due to the design of CMake system, CMake variables from Taichi and its submodules could get messed up in certain circumstances. Refer to the following two steps to mute warnings from third-party targets.
+
+1. Separate submodule's `CMAKE_CXX_FLAGS` from that configured in Taichi.
+2. Remove "-Wall" option from submodule's `CMAKE_CXX_FLAGS`.
+
+### How to mute specific warning-types across the entire Taichi project
+Search for the option to mute certain warning-types on [Clang Compiler User Manual](https://clang.llvm.org/docs/UsersManual.html), usually it starts with `-Wno-`. In the comments, please explain what the warning does and why we should ignore it.
+
+The following example can be found in [cmake/TaichiCXXFlags.cmake](https://github.com/taichi-dev/taichi/blob/master/cmake/TaichiCXXFlags.cmake)
+```
+# [Global] Clang warns if a C++ pointer's nullability wasn't marked explicitly (__nonnull, nullable, ...).
+# Nullability seems to be a clang-specific feature, thus we disable this warning.
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-nullability-completeness ")
+
+# [Global] By evaluating "constexpr", compiler throws a warning for functions known to be dead at compile time.
+# However, some of these "constexpr" are debug flags and will be manually enabled upon debuging.
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-unneeded-internal-declaration ")
+```
+
+### How to mute warnings for specific lines of codes (NOT RECOMMENDED)
+In rare situations where the warnings cannot be fixed nor muted via regular attempts, one of the last things you can try is to decorate your code with `#pragma clang diagnostic` macro. Be aware that `#pragma`s are not part of the C++ standard and strongly depend on the compiler's implementation. That is to say, the following solution is neither stable nor elegant.
+
+Wrap the lines of interest with the following two macros, warnings will be ignored for the codes in between.
+
+You may also replace the `-Wall` with a group of specific warning-types for finer control.
+
+```
+#if defined(__clang__)
+  #pragma clang diagnostic push
+  #pragma clang diagnostic ignored "-Wall"
+#endif
+
+{Your Code Goes Here}
+
+#if defined(__clang__)
+  #pragma clang diagnostic pop
+#endif
+```
+
 ##  Still have issues?
 
 If you encounter any issue that is not covered here, feel free to report it by asking us on GitHub discussions or by [opening an issue on GitHub](https://github.com/taichi-dev/taichi/issues/new?labels=potential+bug&template=bug_report.md) and including the details. We are always there to help!