From 2bff28af5d599abce2fa6c604061d2d64d27a4da Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Wed, 19 Jun 2024 18:02:57 -0400 Subject: [PATCH 1/6] DOC: Add linux build instructions --- {{cookiecutter.project_name}}/BUILD_LINUX.md | 40 ++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 {{cookiecutter.project_name}}/BUILD_LINUX.md diff --git a/{{cookiecutter.project_name}}/BUILD_LINUX.md b/{{cookiecutter.project_name}}/BUILD_LINUX.md new file mode 100644 index 0000000..a10a77c --- /dev/null +++ b/{{cookiecutter.project_name}}/BUILD_LINUX.md @@ -0,0 +1,40 @@ +# Build and Package {{cookiecutter.project_name}} + +This document summarizes how to build and package {{cookiecutter.project_name}} on Linux. + +{{cookiecutter.project_name}} is a custom Slicer application. Reading the [3D Slicer Developer Documentation](https://slicer.readthedocs.io/en/latest/developer_guide/index.html) may help answer additional questions. + +The initial source files were created using [KitwareMedical/SlicerCustomAppTemplate](https://github.com/KitwareMedical/SlicerCustomAppTemplate). + +## Clone + +```sh +git clone https://github.com/{{cookiecutter.github_organization}}/{{cookiecutter.github_project}}.git +``` + +## Prerequisites + +Install the prerequisites as described in the [Slicer documentation for building on Linux](https://slicer.readthedocs.io/en/latest/developer_guide/build_instructions/linux.html). This includes development tools, support libraries, and Qt. + +## Build + +Note: The build process can take hours. + +Assuming that Qt 5.15.2 was installed to `/opt/qt/` (if not then adjust the command accordingly): + +```sh +mkdir {{cookiecutter.app_name}}-superbuild +cd {{cookiecutter.app_name}}-superbuild +cmake -DCMAKE_BUILD_TYPE:STRING=Release -DQt5_DIR:PATH=/opt/qt/5.15.2/gcc_64/lib/cmake/Qt5 -S ../{{cookiecutter.github_project}} -B . +make -j +``` + +Once the application is built, there will be an "inner build" inside the superbuild folder, located at `{{cookiecutter.app_name}}-superbuild/Slicer-build`. The application executable is contained in this inner build folder. + +## Package + +From the inner build folder: + +```sh +make package +``` From 5ec81a156bee6abc73a91da7a1fcbf4951b16622 Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Wed, 19 Jun 2024 17:01:12 -0400 Subject: [PATCH 2/6] DOC: Rename BUILD to BUILD_WINDOWS This makes room for linux build instructions to be added --- {{cookiecutter.project_name}}/{BUILD.md => BUILD_WINDOWS.md} | 0 {{cookiecutter.project_name}}/README.md | 3 ++- 2 files changed, 2 insertions(+), 1 deletion(-) rename {{cookiecutter.project_name}}/{BUILD.md => BUILD_WINDOWS.md} (100%) diff --git a/{{cookiecutter.project_name}}/BUILD.md b/{{cookiecutter.project_name}}/BUILD_WINDOWS.md similarity index 100% rename from {{cookiecutter.project_name}}/BUILD.md rename to {{cookiecutter.project_name}}/BUILD_WINDOWS.md diff --git a/{{cookiecutter.project_name}}/README.md b/{{cookiecutter.project_name}}/README.md index 7056093..d1c54a7 100644 --- a/{{cookiecutter.project_name}}/README.md +++ b/{{cookiecutter.project_name}}/README.md @@ -16,6 +16,7 @@ _List key features_ ## Development - [Contributing](CONTRIBUTING.md) -- [Building](BUILD.md) +- [Building on Windows](BUILD_WINDOWS.md) +- [Building on Linux](BUILD_LINUX.md) ![{{cookiecutter.project_name}} by {{cookiecutter.org_name}}](Applications/{{cookiecutter.app_name}}App/Resources/Images/LogoFull.png?raw=true) From fcdcfa7d2f8838c408af12411d3b9fc82f24c7f1 Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Wed, 19 Jun 2024 17:22:49 -0400 Subject: [PATCH 3/6] DOC: Remove instruction to email for access This doesn't make sense for a number of reasons: - Not every organization has a domain name like that or does emails like that with first and last names. - Email is not always the preferred mode of contact. - If someone can read this BUILD_WINDOWS.md document, then they already have read access to the repo and do not need to request further access. Write access is not needed for cloning and building. --- {{cookiecutter.project_name}}/BUILD_WINDOWS.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/{{cookiecutter.project_name}}/BUILD_WINDOWS.md b/{{cookiecutter.project_name}}/BUILD_WINDOWS.md index e6cbdca..122e592 100644 --- a/{{cookiecutter.project_name}}/BUILD_WINDOWS.md +++ b/{{cookiecutter.project_name}}/BUILD_WINDOWS.md @@ -16,9 +16,6 @@ The initial source files were created using [KitwareMedical/SlicerCustomAppTempl - Setup [your git username](https://help.github.com/articles/setting-your-username-in-git) and [your git email](https://help.github.com/articles/setting-your-email-in-git). - - If not already done, email `FirstName LastName ` to be granted access to - the [{{cookiecutter.github_organization}}/{{cookiecutter.github_project}}](https://github.com/{{cookiecutter.github_organization}}/{{cookiecutter.github_project}}) repository. - ## Checkout 1. Start `Git Bash` From fc97639d5fb63b5bb4bc94ae519b28bb9f6594ef Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Wed, 19 Jun 2024 17:40:51 -0400 Subject: [PATCH 4/6] DOC: Be more vague about build time Build time depends on many factors and evolves as Slicer does --- {{cookiecutter.project_name}}/BUILD_WINDOWS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/{{cookiecutter.project_name}}/BUILD_WINDOWS.md b/{{cookiecutter.project_name}}/BUILD_WINDOWS.md index 122e592..4cbe2e4 100644 --- a/{{cookiecutter.project_name}}/BUILD_WINDOWS.md +++ b/{{cookiecutter.project_name}}/BUILD_WINDOWS.md @@ -32,7 +32,7 @@ Note: use short source and build directory names to avoid the [maximum path leng ## Build -Note: The build process will take approximately 3 hours. +Note: The build process can take hours. Option 1: CMake GUI and Visual Studio (Recommended) From 8c7d5935347bb40b0b8efa62ed1071b05c8ee193 Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Thu, 20 Jun 2024 09:46:41 -0400 Subject: [PATCH 5/6] DOC: Edit linux build instructions based on review Co-authored-by: Jean-Christophe Fillion-Robin --- {{cookiecutter.project_name}}/BUILD_LINUX.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/{{cookiecutter.project_name}}/BUILD_LINUX.md b/{{cookiecutter.project_name}}/BUILD_LINUX.md index a10a77c..8dfaacd 100644 --- a/{{cookiecutter.project_name}}/BUILD_LINUX.md +++ b/{{cookiecutter.project_name}}/BUILD_LINUX.md @@ -23,17 +23,22 @@ Note: The build process can take hours. Assuming that Qt 5.15.2 was installed to `/opt/qt/` (if not then adjust the command accordingly): ```sh -mkdir {{cookiecutter.app_name}}-superbuild -cd {{cookiecutter.app_name}}-superbuild -cmake -DCMAKE_BUILD_TYPE:STRING=Release -DQt5_DIR:PATH=/opt/qt/5.15.2/gcc_64/lib/cmake/Qt5 -S ../{{cookiecutter.github_project}} -B . -make -j +cmake \ + -DCMAKE_BUILD_TYPE:STRING=Release \ + -DQt5_DIR:PATH=/opt/qt/5.15.2/gcc_64/lib/cmake/Qt5 \ + -S {{cookiecutter.github_project}} \ + -B {{cookiecutter.github_project}}-SuperBuild-Release + +make -j ``` -Once the application is built, there will be an "inner build" inside the superbuild folder, located at `{{cookiecutter.app_name}}-superbuild/Slicer-build`. The application executable is contained in this inner build folder. +where `` is the number of parallel builds. As a rule of thumb, many use the `number of CPU threads - 1` as the number of parallel builds. + +Once the application is built, there will be an _inner build_ inside the _superbuild_ folder, located at `{{cookiecutter.app_name}}-SuperBuild-Release/Slicer-build`. The application executable is contained in this _inner build_ folder. ## Package -From the inner build folder: +From the _inner build_ folder: ```sh make package From 3371856ea0a56a751a0c6db34579aea74669edf3 Mon Sep 17 00:00:00 2001 From: Ebrahim Ebrahim Date: Tue, 20 Aug 2024 13:15:05 -0400 Subject: [PATCH 6/6] DOC: Remove Qt var from main linux build instructions It's only needed on ubuntu 20.04 pretty much so it should not be there in the main instruction. --- {{cookiecutter.project_name}}/BUILD_LINUX.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_name}}/BUILD_LINUX.md b/{{cookiecutter.project_name}}/BUILD_LINUX.md index 8dfaacd..e06ecaa 100644 --- a/{{cookiecutter.project_name}}/BUILD_LINUX.md +++ b/{{cookiecutter.project_name}}/BUILD_LINUX.md @@ -20,7 +20,7 @@ Install the prerequisites as described in the [Slicer documentation for building Note: The build process can take hours. -Assuming that Qt 5.15.2 was installed to `/opt/qt/` (if not then adjust the command accordingly): +Build: ```sh cmake \ @@ -28,11 +28,13 @@ cmake \ -DQt5_DIR:PATH=/opt/qt/5.15.2/gcc_64/lib/cmake/Qt5 \ -S {{cookiecutter.github_project}} \ -B {{cookiecutter.github_project}}-SuperBuild-Release - +cd {{cookiecutter.github_project}}-SuperBuild-Release make -j ``` where `` is the number of parallel builds. As a rule of thumb, many use the `number of CPU threads - 1` as the number of parallel builds. +On Ubuntu 20.04, the default Qt5 packages are too old and so the Slicer documentation linked above should have suggested a method of installing Qt 5.15.2; +if you installed it to `/opt/qt`, for example, then an extra option like `-DQt5_DIR:PATH=/opt/qt/5.15.2/gcc_64/lib/cmake/Qt5` would be needed in the `cmake` command above. Once the application is built, there will be an _inner build_ inside the _superbuild_ folder, located at `{{cookiecutter.app_name}}-SuperBuild-Release/Slicer-build`. The application executable is contained in this _inner build_ folder.