refactor: categorize examples/ directory and update scripts/run_examples.py (#42)

* docs: remove the `examples/` structure diagram

* docs: update `README.md` to reflect the new file structure of `examples/`

* style: ruff format `scripts/run_examples.py`

* refactor: change the directory structure of `examples/` to categorize different types of examples and update `scripts/run_examples.py`
    - restructure the `examples/` to categorize different types of examples
    - update `scripts/run_examples.py` to accommodate this change and be able to specify an example directory, specific examples, or fuzzy example names

Author: Ziminli

README.md

@@ -173,18 +173,20 @@ After having a successful build and a complete `cluster.yaml`, we are ready for
 ### 1. Run Internal Examples
 
 #### 1.1. Run a Single Example
-To run an internal example program (e.g., `examples/all_reduce.cc`), just run: 
+The repository organizes example suites by collective paradigm layout under `examples/`.
+
+To run an internal example program (e.g., `examples/mpi/all_reduce.cc`), just run: 
 
 ```bash
 # Build and run the executable across the cluster based on the config specified in your `cluster.yaml`
-icclrun --config [path-to-your-cluster.yaml] --build all_reduce [program args]
+icclrun --config [path-to-your-cluster.yaml] --build mpi/all_reduce [program args]
 ```
 
 - `--config / -c` : Path to the cluster YAML file.
 - `--build` : Instructs `icclrun` to compile the library on each node before execution. If omitted, `icclrun` assumes the library is already installed at a consistent location.
 - `--launcher` : Specify the backend launcher to be used. Default to `ompi`.
 
-The executable (e.g., `all_reduce`) and its arguments follow the options.
+The executable (e.g., `mpi/all_reduce`) and its arguments follow the options.
 
 For more details, run:
 
@@ -207,7 +209,7 @@ chmod +x ./scripts/run_examples.sh
 For all the options of the script, see:
 
 ```bash
-./run_examples --help
+./scripts/run_examples.py --help
 ```
 
 ### 2. Run a Custom User Program

examples/CMakeLists.txt

@@ -1,47 +1,61 @@
 file(GLOB_RECURSE EXAMPLE_SOURCES "*.cc")
 
 foreach(source_file ${EXAMPLE_SOURCES})
-    get_filename_component(example_name ${source_file} NAME_WE)
+    file(RELATIVE_PATH rel_file "${CMAKE_CURRENT_SOURCE_DIR}" "${source_file}")
 
-    add_executable(${example_name} ${source_file})
+    get_filename_component(file_dir ${rel_file} DIRECTORY)
+    get_filename_component(file_we ${rel_file} NAME_WE)
 
-    target_link_libraries(${example_name} PRIVATE infiniccl)
+    if(file_dir)
+        string(REPLACE "/" "_" target_name "${file_dir}_${file_we}")
+    else()
+        set(target_name ${file_we})
+    endif()
+
+    add_executable(${target_name} ${source_file})
+
+    set_target_properties(${target_name} PROPERTIES
+        OUTPUT_NAME "${file_we}"
+        RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/${file_dir}"
+    )
+
+    target_link_libraries(${target_name} PRIVATE infiniccl)
 
     # Add runtime and backend dependencies for direct runtime/backend usage.
     if(WITH_NVIDIA)
-        target_link_libraries(${example_name} PRIVATE CUDA::cudart)
+        target_link_libraries(${target_name} PRIVATE CUDA::cudart)
     endif()
 
     if(WITH_ILUVATAR)
         set_source_files_properties(${source_file} PROPERTIES LANGUAGE CXX)
-        set_target_properties(${example_name} PROPERTIES
+        set_target_properties(${target_name} PROPERTIES
             RULE_LAUNCH_COMPILE "${ILUVATAR_CUDA_COMPILER} "
         )
-        target_compile_options(${example_name} PRIVATE ${ILUVATAR_CUDA_FLAGS} "-Wno-unused-command-line-argument")
-        target_link_libraries(${example_name} PRIVATE CUDA::cudart CUDA::cuda_driver)
+        target_compile_options(${target_name} PRIVATE ${ILUVATAR_CUDA_FLAGS} "-Wno-unused-command-line-argument")
+        target_link_libraries(${target_name} PRIVATE CUDA::cudart CUDA::cuda_driver)
     endif()
 
     if(WITH_METAX)
-        target_link_libraries(${example_name} PRIVATE ${MACA_RUNTIME_LIB})
-        target_compile_options(${example_name} PRIVATE "-x" "maca")
+        target_link_libraries(${target_name} PRIVATE ${MACA_RUNTIME_LIB})
+        target_compile_options(${target_name} PRIVATE "-x" "maca")
     endif()
 
     if(WITH_MOORE)
-        target_link_libraries(${example_name} PRIVATE ${MUSART_LIB})
-        target_compile_options(${example_name} PRIVATE "-x" "musa")
+        target_link_libraries(${target_name} PRIVATE ${MUSART_LIB})
+        target_compile_options(${target_name} PRIVATE "-x" "musa")
     endif()
 
     if(WITH_CAMBRICON)
-        target_link_libraries(${example_name} PRIVATE ${CAMBRICON_RUNTIME_LIB})
+        target_link_libraries(${target_name} PRIVATE ${CAMBRICON_RUNTIME_LIB})
     endif()
 
     if(WITH_OMPI OR WITH_MPICH)
-        target_link_libraries(${example_name} PRIVATE MPI::MPI_CXX)
+        target_link_libraries(${target_name} PRIVATE MPI::MPI_CXX)
     endif()
 
     # Explicitly allow examples to "peek" into the internal `src` and binary dirs.
     # This is necessary because these were marked `PRIVATE` in the library's CMake.
-    target_include_directories(${example_name} PRIVATE 
+    target_include_directories(${target_name} PRIVATE 
         ${CMAKE_CURRENT_SOURCE_DIR}
         "${PROJECT_SOURCE_DIR}/src"         # For internal templates like `runtime.h`.
         "${CMAKE_BINARY_DIR}/src"           # For the generated `backend_manifest.h`.