Merge pull request #2538 from wangkuiyi/generic.cmake-comments

Rewrite tutorial comments in generic.cmake

cmake/generic.cmake

@@ -12,9 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-# To simplify the build process of PaddlePaddle, we defined couple of
-# fundamental abstractions, e.g., how to build library, binary and
-# test in C++, CUDA and Go.
+
+
+# generic.cmake defines CMakes functions that look like Bazel's
+# building rules (https://bazel.build/).
+#
 # 
 # -------------------------------------------
 #     C++        CUDA C++       Go
@@ -24,67 +26,57 @@
 # cc_test       nv_test      go_test
 # -------------------------------------------
 # 
-# cmake_parse_arguments can help us to achieve this goal.
-# https://cmake.org/cmake/help/v3.0/module/CMakeParseArguments.html
+# To build a static library example.a from example.cc using the system
+#  compiler (like GCC):
 # 
-# cc_library|nv_library(<target_name> [STATIC SHARED] SRCS <file>... DEPS <libs>...)
+#   cc_library(example SRCS example.cc)
 # 
-# cc_library and nv_library can generate *.a, or *.so
-# if the corresponding keyword STATIC or SHARED is specified.
+# To build a static library example.a from multiple source files
+# example{1,2,3}.cc:
 # 
-# cc_binary|nv_binary(<target_name> SRCS <file>... DEPS <libs>...)
+#   cc_library(example SRCS example1.cc example2.cc example3.cc)
 # 
-# cc_binary and nv_binary can build souce code and link the dependent
-# libraries to generate a binary.
+# To build a shared library example.so from example.cc:
 # 
-# cc_test|nv_test(<target_name> SRCS <file>... DEPS <libs>...)
+#   cc_library(example SHARED SRCS example.cc)
 # 
-# cc_test and nv_test can build test code, link gtest and other dependent
-# libraries to generate test suite.
+# To build a library using Nvidia's NVCC from .cu file(s), use the nv_
+# prefixed version:
 # 
-# For example, in one folder, it contains
-#   ddim{.h, .cc, _test.cc, _test.cu}
-#   place{.h, cc, _test.cc}
+#   nv_library(example SRCS example.cu)
 # 
-# We can add build script as follows: 
+# To specify that a library new_example.a depends on other libraies:
 # 
-# cc_library(place STATIC SRCS place.cc)
+#   cc_library(new_example SRCS new_example.cc DEPS example)
 # 
-# place.cc -> place.a
-# cc_library's STATIC OPTION will generate libplace.a.
+# Static libraries can be composed of other static libraries:
 # 
-# cc_test(place_test
-#    SRCS place_test.cc
-#    DEPS place glog gflags)
+#   cc_library(composed DEPS dependent1 dependent2 dependent3)
 # 
-# place_test.cc, place, glog, gflags -> place_test
-# cc_test will combine place_test.cc, libplace.a with libglog.a.
-# and libgflags.a to generate place_test.
+# To build an executable binary file from some source files and
+# dependent libraries:
 # 
-# cc_library(ddim STATIC SRCS ddim.cc)
+#   cc_binary(example SRCS main.cc something.cc DEPS example1 example2)
 # 
-# ddim.cc -> ddim.a
-# cc_library's STATIC OPTION will generate libddim.a.
+# To build an executable binary file using NVCC, use the nv_ prefixed
+# version:
 # 
-# cc_test(ddim_test
-#    SRCS ddim_test.cc
-#    DEPS ddim)
+#   nv_binary(example SRCS main.cc something.cu DEPS example1 example2)
 # 
-# ddim_test.cc, ddim.a -> ddim_test
-# cc_test will build ddim_test.cc with libddim.a to generate ddim_test.
+# To build a unit test binary, which is an executable binary with
+# GoogleTest linked:
 # 
-# nv_test(dim_test
-#    SRCS dim_test.cu
-#    DEPS ddim)
+#   cc_test(example_test SRCS example_test.cc DEPS example)
 # 
-# dim_test.cu, ddim.a -> dim_test
-# nv_test will build dim_test.cu with libddim.a to generate dim_test.
+# To build a unit test binary using NVCC, use the nv_ prefixed version:
 # 
-# cc_library(framework DEPS place ddim)
+#   nv_test(example_test SRCS example_test.cu DEPS example)
 #
-# place.a, ddim.a -> framework.a
-# If no SRCS exists, merging libplace.a and libddim.a to generate libframework.a.
+# It is pretty often that executable and test binaries depend on
+# pre-defined external libaries like glog and gflags defined in
+# /cmake/external/*.cmake:
 #
+#   cc_test(example_test SRCS example_test.cc DEPS example glog gflags)
 
 if(NOT APPLE)
     find_package(Threads REQUIRED)