Improvements to run list and run build (nvidia-holoscan#639)

* Improve ./run list results Signed-off-by: Alexis Girault <[email protected]> * Allow to build operators with run script Also: - verify input validity using the improve listing from the last commit - allow passing a path to the app/operator dir, for improve UX by leveraging terminal autocompletion Signed-off-by: Alexis Girault <[email protected]> * Allow to build packages with run script Signed-off-by: Alexis Girault <[email protected]> * Style improvement to remaining _desc() Signed-off-by: Alexis Girault <[email protected]> * Update README for build instructions Signed-off-by: Alexis Girault <[email protected]> * Update README.md Co-authored-by: Tom Birdsong <[email protected]> Signed-off-by: Alexis Girault <[email protected]> --------- Signed-off-by: Alexis Girault <[email protected]> Signed-off-by: Alexis Girault <[email protected]> Co-authored-by: Tom Birdsong <[email protected]>
cliffburdick · Jan 23, 2025 · 22e06ae · 22e06ae
1 parent 5e4c75f
commit 22e06ae
Show file tree

Hide file tree

Showing 2 changed files with 203 additions and 140 deletions.
diff --git a/README.md b/README.md
@@ -25,12 +25,13 @@ This is a central repository for the NVIDIA Holoscan AI sensor processing commun
 This repository is a collection of applications and extensions created by the Holoscan AI sensor processing community.
 The following directories make up the core of this repo:
 
-- Example applications: Visit [`applications`](./applications) to explore an evolving collection of example
+- **Example applications**: Visit [`applications`](./applications) to explore an evolving collection of example
   applications built on the NVIDIA Holoscan platform. Examples are available from NVIDIA, partners, and
-  community collaborators.
-- Community components: Visit [`operators`](./operators/) and [`gxf_extensions`](./gxf_extensions) to explore
+  community collaborators, and provide a demonstration of the SDK capabilities.
+- **Community components**: Visit [`operators`](./operators/) and [`gxf_extensions`](./gxf_extensions) to explore
   reusable Holoscan modules.
-- Tutorials: Visit [`tutorials`](./tutorials/) for extended walkthroughs and tips for the Holoscan platform.
+- **Package configurations**: Visit [`pkg`](./pkg/) for a list of debian package to generate, to distribute operators and applications for easier development.
+- **Tutorials**: Visit [`tutorials`](./tutorials/) for extended walkthroughs and tips for the Holoscan platform.
 
 Visit the [Holoscan SDK User Guide](https://docs.nvidia.com/holoscan/sdk-user-guide/overview.html) to learn more about the NVIDIA Holoscan AI sensor processing platform. You can also chat with the [Holoscan-GPT](https://chatgpt.com/g/g-M6hMJimGa-holochatgpt) Large Language Model to learn about using Holoscan SDK, ask questions, and get code help. Holoscan-GPT requires an OpenAI account.
 
@@ -52,7 +53,7 @@ We strongly recommend new users follow our [Container Build](#container-build-re
 
 If you prefer to build locally without `docker`, take a look at our [Native Build](./doc/developer.md#native-build) instructions.
 
-Once your development environment is configured you may move on to [Building Applications](#building-applications).
+Once your development environment is configured you may move on to [Building the Holohub components you are interested in](#building-operators-applications-and-packages).
 
 ## Container Build (Recommended)
 
@@ -66,7 +67,7 @@ To build and run in a containerized environment you will need:
 You will also need to set up your NVIDIA NGC credentials at [ngc.nvidia.com](https://catalog.ngc.nvidia.com/).
 
 ### Fetch
-  
+
 Clone the repository to your local system:
 ```sh
 $ git clone https://www.github.com/nvidia-holoscan/holohub.git
@@ -104,7 +105,7 @@ Launch the Docker container environment:
 $ ./dev_container launch
 ```
 
-You are now ready to run applications! You may jump to the [Running Applications](#running-applications) section to get started.
+You are now ready to [build Holohub operators, applications, or packages!](#building-operators-applications-and-packages)
 
 ***Note***  The `launch` option will use the default development container built using Holoscan SDK's container from NGC for the local GPU. The script will also inspect for available video devices (V4L2, AJA capture boards, Deltacast capture boards) and the presence of Deltacast's Videomaster SDK and map it into the development container.
 
@@ -113,7 +114,7 @@ See also: [Advanced Launch Options](/doc/developer.md#advanced-launch-options-co
 ### Platform Notes (Container)
 
 The development container has been tested on the following platforms:
-- x86_x64 workstation with multiple RTX GPUs
+- x86_64 workstation with multiple RTX GPUs
 - Clara AGX Dev Kit (dGPU mode)
 - IGX Orin Dev Kit (dGPU and iGPU mode)
 - AGX Orin Dev Kit (iGPU)
@@ -124,47 +125,56 @@ The development container has been tested on the following platforms:
 
 (2) When building Holoscan SDK on AGX Orin Dev Kit from source please add the option  ```--cudaarchs all``` to the ```./run build``` command to include support for AGX Orin's iGPU.
 
-# Building Applications
+# Building Operators, Applications, and Packages
 
-_Make sure you have installed the [prerequisites](#prerequisites) before attempting to build reference applications._
+> _Make sure you have either launched your [development container](#container-build-recommended) or [set up your local environment](./doc/developer.md#native-build) before attempting to build Holohub components._
 
-Reference applications based on the Holoscan platform may be found under the [applications](./applications/) directory. Reference applications aim to provide a demonstration of the SDK capabilities.
+This repository provides a convenience `run` script to abstract some of the CMake build process below.
 
-This repository provides a convenient `run` script to build and run applications in your development environment.
-To build an application:
+Run the following to list existing components available to build:
 
-```bash
-  ./run build <application>
-```
+  ```bash
+  ./run list
+  ```
+
+Then run the following to build the component of your choice, using either its name or its path:
+
+  ```bash
+  # Build using the component name
+  ./run build <package|application|operator>
+  # Ex: ./run build endoscopy_tool_tracking
 
-When the build is successful you can [run applications](#running-applications).
+  # Build using the component path
+  ./run build ./<pkg|applications|operator>/<name>
+  # Ex: ./run build ./applications/endoscopy_tool_tracking/
+  ```
+
+The build artifacts will be created under `./build/<component_name>` by default to isolate them from other components which might have different build environment requirements. You can override this behavior and other defaults, see `./run build --help` for more details.
 
 # Running Applications
 
 To list all available applications you can run the following command:
-```bash
-  ./run list
-```
+
+  ```bash
+  ./run list_apps
+  ```
 
 Then you can run the application using the command:
-```bash
-  ./run launch <application>
-```
 
-For example, to run the tool tracking endoscopy application:
-```bash
-  ./run launch endoscopy_tool_tracking
-```
+  ```bash
+  ./run launch <application>
+  # Ex: ./run launch endoscopy_tool_tracking
+  ```
 
 Several applications are implemented in both C++ and Python programming languages.
 You can request a specific implementation as a trailing argument to the `./run launch` command
 or omit the argument to use the default language.
 For instance, the following command will run the Python implementation of the tool tracking
 endoscopy application:
 
-```bash
-  ./run launch endoscopy_tool_tracking python
-```
+  ```bash
+    ./run launch endoscopy_tool_tracking python
+  ```
 
 The run script reads the "run" command from the metadata.json file for a given application and runs from the "workdir" directory.
 Make sure you build the application (if applicable) before running it.
@@ -173,14 +183,15 @@ Make sure you build the application (if applicable) before running it.
 
 You can run the command below to reset your `build` directory:
 
-```sh
-./run clear_cache
-```
+  ```sh
+  ./run clear_cache
+  ```
 
 In some cases you may also want to clear out datasets downloaded by applications to the `data` folder:
-```sh
-rm -rf ./data
-```
+
+  ```sh
+  rm -rf ./data
+  ```
 
 Note that many applications supply custom container environments with build and runtime dependencies.
 Failing to clean the build cache between different applications may result in unexpected behavior where build