CI - set the default stage install dir for DBE.

On DBE the stage install dir must be inside the docker volume anyway, so set a sane default value when it is not explicitly specified.

website - simplify the DBE quick start section.

.github/workflows/main.yml

@@ -115,7 +115,7 @@ jobs:
         if: matrix.platform != 'linux-clang-tidy' && matrix.platform != 'linux-clang-format'
       - name: Scaffolding - install
         run: |
-          script/dockerized.sh ${PLATFORM/-*} rake install[~/stage]
+          script/dockerized.sh ${PLATFORM/-*} rake install
           if [[ $PLATFORM == android ]]; then touch build/cache/.gradle/mark; fi
         if: matrix.platform != 'linux-clang-tidy' && matrix.platform != 'linux-clang-format'
       - name: Scaffolding - new
@@ -124,7 +124,7 @@ jobs:
       - name: Scaffolding - build
         run: |
           cd build/cache/projects/UrhoApp
-          URHO3D_HOME=/home/urho3d/stage/usr/local script/dockerized.sh ${PLATFORM/-*}
+          script/dockerized.sh ${PLATFORM/-*}
         if: matrix.platform != 'linux-clang-tidy' && matrix.platform != 'linux-clang-format'
       - name: Scaffolding - test
         run: |

rakefile

@@ -30,7 +30,10 @@ task :cmake => [:init] do
       system 'bash', '-c', 'rm -rf ~/.{ccache,gradle}' or abort 'Failed to clear the build cache'
     end
   end
-  next if ENV['PLATFORM'] == 'android' || (Dir.exist?("#{build_tree}") and not ARGV.include?('cmake'))
+  next if ENV['PLATFORM'] == 'android' || (Dir.exists?("#{build_tree}") and not ARGV.include?('cmake'))
+  if dockerized? && !ENV['URHO3D_HOME']
+    ENV['URHO3D_HOME'] = "~/stage-#{ENV['PLATFORM']}/usr/local"
+  end
   script = "script/cmake_#{ENV['GENERATOR']}#{ENV['OS'] ? '.bat' : '.sh'}"
   build_options = /linux|macOS|win/ =~ ENV['PLATFORM'] ? '' : "-D #{ENV['PLATFORM'].upcase}=1"
   File.readlines('script/.build-options').each { |var|
@@ -103,6 +106,8 @@ task :install, [:prefix] => [:init] do |_, args|
   if ENV['PLATFORM'] == 'android'
     Rake::Task[:gradle].invoke('publishToMavenLocal')
     next
+  elsif dockerized?
+    args.with_defaults(:prefix => "~/stage-#{ENV['PLATFORM']}")
   end
   wrapper = args[:prefix] && !ENV['OS'] ? "DESTDIR=#{verify_path(args[:prefix])}" : ''
   system build_target('install', wrapper) or abort

script/.build-options

@@ -6,6 +6,7 @@ IOS
 TVOS
 URHO3D_64BIT
 URHO3D_ANGELSCRIPT
+URHO3D_FORCE_AS_MAX_PORTABILITY
 URHO3D_LUA
 URHO3D_LUAJIT
 URHO3D_LUAJIT_AMALG

script/.env-file

@@ -64,6 +64,7 @@ URHO3D_DOCS
 URHO3D_DOCS_QUIET
 URHO3D_EXTRAS
 URHO3D_FILEWATCHER
+URHO3D_FORCE_AS_MAX_PORTABILITY
 URHO3D_GENERATEBINDINGS
 URHO3D_HASH_DEBUG
 URHO3D_HOME
@@ -86,7 +87,6 @@ URHO3D_PCH
 URHO3D_PHYSICS
 URHO3D_PLAYER
 URHO3D_PROFILING
-URHO3D_TRACY_PROFILING
 URHO3D_SAFE_LUA
 URHO3D_SAMPLES
 URHO3D_SCP_TO_TARGET
@@ -99,6 +99,7 @@ URHO3D_TESTING
 URHO3D_TEST_TIMEOUT
 URHO3D_THREADING
 URHO3D_TOOLS
+URHO3D_TRACY_PROFILING
 URHO3D_UPDATE_SOURCE_TREE
 URHO3D_URHO2D
 URHO3D_USE_LIB64_RPM

website/docs/getting-started/getting-started.module.scss

@@ -0,0 +1,14 @@
+// A quick and dirty hack to keep the tab panel with less content to have the same height as others
+div > div > div > div > div > div {
+  .buildUrho3D + & {
+    min-height: 164px;
+  }
+
+  .buildUrhoApp + & {
+    min-height: 142px;
+  }
+
+  .requirements + & {
+    min-height: 340px;
+  }
+}

website/docs/getting-started/installation.mdx

@@ -0,0 +1,146 @@
+---
+sidebar_position: 20
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Styles from './getting-started.module.scss';
+
+# Installation
+
+Using native and cross-compiler toolchains to build and install Urho3D library
+
+## Requirements
+
+First prepares the build environment by installing a compiler toolchain for your target platform, and the required build tools. The compiler can be GCC, Clang, MSVC, MinGW-w64, or the one bundled in the SDK like Android SDK, Emscripten SDK, etc. On Ubuntu you can easily prepare the build environment by installing the `build-essential` package, on Windows by installing Visual Studio IDE, and on macOS by installing Xcode IDE. However, for cross-compiling usually you have to download and install the corresponding SDK manually. Make sure at the minimum the build environment has these build tools installed:
+- CMake
+- Git
+- Rake
+
+Optionally these as well:
+- ccache - for speeding up the build
+- Doxygen and Graphviz - for building documentation
+- Make or Ninja - for building with terminal/console
+
+:::caution
+
+Cross-compiling on Windows host requires MinGW-w64 to be installed too as it is required to build the host-tools on the fly while cross-compiling the library for the target platform.
+
+:::
+
+Although Urho3D project has included all required third-party libraries as source code, there may be system-level dependency packages that must be satisfied before Urho3D can be built from source successfully. The list below is by no mean comprehensive nor canonical, but it should be the minimal to get started.
+
+:::note
+
+This may change in the future when the project uses better package manager and Modern CMake. Ideally, the project should bootstrap itself with more ease than currently is.
+
+:::
+
+<Tabs
+  className={Styles.requirements}
+  groupId={'target-platform'}
+  defaultValue={'android'}
+  values={[
+    {label: 'Android', value: 'android'},
+    {label: 'Apple', value: 'apple'},
+    {label: 'Arm', value: 'arm'},
+    {label: 'Linux', value: 'linux'},
+    {label: 'RPI', value: 'rpi'},
+    {label: 'Web', value: 'web'},
+    {label: 'Windows', value: 'win'},
+  ]
+  }>
+  <TabItem value={'android'}>
+
+```
+Android Studio (and IntelliJ IDEA) should already provide everything required
+Remember to complete the Android SDK installation as per instructed by IDE
+Tested tool version: 29.0.2
+Tested NDK version: 21.3.6528147
+```
+
+  </TabItem>
+  <TabItem value={'apple'}>
+
+```
+# Xcode should already provide everything required
+# You may use "homebrew" to install other missing development packages, like "openssl"
+```
+
+  </TabItem>
+  <TabItem value={'arm'}>
+
+```bash
+# Urho3D only supports ARM platform on Linux OS, so it has the same deps as building Linux platform
+apt install \
+    # !!! MESA is not needed on system with proprietary kernel module/driver !!!
+    libgl1-mesa-dev \
+    # Display server, still default to X11 at the moment
+    libx11-dev \
+    # Sound server, still default to PulseAudio at the moment
+    libpulse-dev \
+    # D-BUS and udev, for game controller hot-plugging
+    libdbus-1-dev libudev-dev \
+    # IME, optional for Chinese/Japanese/Korean text inputting
+    libibus-1.0-dev \
+    # SSL, optional for secure networking
+    libssl-dev
+```
+
+  </TabItem>
+  <TabItem value={'linux'}>
+
+```bash
+# Building as 32-bit on a 64-bit host requires installation of 32-bit development packages too
+apt install \
+    # !!! MESA is not needed on system with proprietary kernel module/driver !!!
+    libgl1-mesa-dev \
+    # Display server, still default to X11 at the moment
+    libx11-dev \
+    # Sound server, still default to PulseAudio at the moment
+    libpulse-dev \
+    # D-BUS and udev, for game controller hot-plugging
+    libdbus-1-dev libudev-dev \
+    # IME, optional for Chinese/Japanese/Korean text inputting
+    libibus-1.0-dev \
+    # SSL, optional for secure networking
+    libssl-dev
+```
+
+  </TabItem>
+  <TabItem value={'rpi'}>
+
+```bash
+# This list was compiled for RPI3 in mind, with proprietary Broadcom Video Core proprietary driver
+# However, you can still use it for RPI4 by also installing MESA and X11 on top of it
+apt install \
+    # Sound server, still default to PulseAudio at the moment
+    libpulse-dev \
+    # D-BUS and udev, for game controller hot-plugging
+    libdbus-1-dev libudev-dev \
+    # Generic Linux input driver
+    libevdev2 \
+    # IME, optional for Chinese/Japanese/Korean text inputting
+    libibus-1.0-dev \
+    # SSL, optional for secure networking
+    libssl-dev
+```
+
+  </TabItem>
+  <TabItem value={'web'}>
+
+```
+# Emscripten SDK should already provide everything required
+# Tested SDK version: 2.0.8
+```
+
+  </TabItem>
+  <TabItem value={'win'}>
+
+```
+# Visual Studio should already provide everything required
+# Similarly for MinGW-w64
+```
+
+  </TabItem>
+</Tabs>

website/docs/getting-started/quick-start.mdx

@@ -4,16 +4,17 @@ sidebar_position: 10
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import Styles from './getting-started.module.scss'
 
 # Quick Start
 
-Using Dockerized Build Environment to start quickly
+Using Dockerized Build Environment (DBE) to start quickly
 
 There are more than one way to start using the Urho3D library. This section shows you how to start quickly by using docker containers that have the build environment already prepared for you. All you need is a working docker engine on your host system.
 
 :::tip
 
-Skip to the Requirements section, if you cannot use docker engine on your host system.
+Skip to the [Requirements](building-urho3d-library#Requirements) section, if you cannot use docker engine on your host system.
 
 :::
 
@@ -34,10 +35,12 @@ Windows host system requires WSL2.
 Clone the Urho3D project from the main branch, change directory to its project root, and execute the following commands to build and install the library for your desired target platform.
 
 <Tabs
+  className={Styles.buildUrho3D}
   groupId={'target-platform'}
   defaultValue={'android'}
   values={[
     {label: 'Android', value: 'android'},
+    {label: 'Apple', value: 'apple'},
     {label: 'Arm', value: 'arm'},
     {label: 'Linux', value: 'linux'},
     {label: 'RPI', value: 'rpi'},
@@ -45,75 +48,83 @@ Clone the Urho3D project from the main branch, change directory to its project r
     {label: 'Windows', value: 'win'},
   ]
   }>
-  <TabItem value="android">
+  <TabItem value={'android'}>
 
 ```bash
 git clone https://github.com/urho3d/Urho3D.git
 cd Urho3D
 # Build Urho3D library
 script/dockerized.sh android
-# Install Urho3D library to Maven local repository mounted from a docker volume
+# Install Urho3D library to Maven local repository
 script/dockerized.sh android rake install
 ```
 
   </TabItem>
-  <TabItem value="arm">
+  <TabItem value={'apple'}>
 
-```bash {3}
+```
+Currently DBE does not support Apple platforms
+However, Urho3D supports Apple platforms using native build environment
+```
+
+  </TabItem>
+  <TabItem value={'arm'}>
+
+```bash
 git clone https://github.com/urho3d/Urho3D.git
 cd Urho3D
 # Build Urho3D library, usually you need to specify extra build options to target a specific ARM board
 script/dockerized.sh arm
-# Install Urho3D library to a stage directory mounted from a docker volume
-script/dockerized.sh arm rake install[~/stage-arm]
+# Install Urho3D library to a local stage directory
+script/dockerized.sh arm rake install
 ```
 
   </TabItem>
-  <TabItem value="linux">
+  <TabItem value={'linux'}>
 
 ```bash
 git clone https://github.com/urho3d/Urho3D.git
 cd Urho3D
 # Build Urho3D library
 script/dockerized.sh linux
-# Install Urho3D library to a stage directory mounted from a docker volume
-script/dockerized.sh linux rake install[~/stage-linux]
+# Install Urho3D library to a local stage directory
+script/dockerized.sh linux rake install
 ```
 
   </TabItem>
-  <TabItem value="rpi">
+  <TabItem value={'rpi'}>
 
-```bash {3}
+```bash
 git clone https://github.com/urho3d/Urho3D.git
 cd Urho3D
 # Build Urho3D library, modify the "RPI_ABI" build option accordingly
 RPI_ABI=RPI4 script/dockerized.sh rpi
-# Install Urho3D library to a stage directory mounted from a docker volume
-script/dockerized.sh rpi rake install[~/stage-rpi]
+# Install Urho3D library to a local stage directory
+script/dockerized.sh rpi rake install
 ```
 
   </TabItem>
-  <TabItem value="web">
+  <TabItem value={'web'}>
 
 ```bash
 git clone https://github.com/urho3d/Urho3D.git
 cd Urho3D
 # Build Urho3D library
 script/dockerized.sh web
-# Install Urho3D library to a stage directory mounted from a docker volume
-script/dockerized.sh web rake install[~/stage-web]
+# Install Urho3D library to a local stage directory
+script/dockerized.sh web rake install
 ```
 
   </TabItem>
-  <TabItem value="win">
+  <TabItem value={'win'}>
 
 ```bash
 git clone https://github.com/urho3d/Urho3D.git
 cd Urho3D
 # Build Urho3D library
 script/dockerized.sh mingw
-# Install Urho3D library to a stage directory mounted from a docker volume
-script/dockerized.sh mingw rake install[~/stage-mingw]
+# Install Urho3D library to a local stage directory
+script/dockerized.sh mingw rake install
 ```
 
   </TabItem>
@@ -126,10 +137,12 @@ The `script/dockerized.sh` spawns one of the docker container based on the speci
 You need an installed Urho3D library for the desired target platform to proceed. Although the Urho3D build system also supports linking the Urho3D library directly from its build tree, this quick start guide will not be discussing it here. Assuming you have been following along from the previous section, execute the following commands to create a new UrhoApp project, and then build it.
 
 <Tabs
+  className={Styles.buildUrhoApp}
   groupId={'target-platform'}
   defaultValue={'android'}
   values={[
     {label: 'Android', value: 'android'},
+    {label: 'Apple', value: 'apple'},
     {label: 'Arm', value: 'arm'},
     {label: 'Linux', value: 'linux'},
     {label: 'RPI', value: 'rpi'},
@@ -137,7 +150,7 @@ You need an installed Urho3D library for the desired target platform to proceed.
     {label: 'Windows', value: 'win'},
   ]
   }>
-  <TabItem value="android">
+  <TabItem value={'android'}>
 
 ```bash
 # Create a new UrhoApp
@@ -148,58 +161,66 @@ script/dockerized.sh android
 ```
 
   </TabItem>
-  <TabItem value="arm">
+  <TabItem value={'apple'}>
+
+```
+Currently DBE does not support Apple platforms
+However, Urho3D supports Apple platforms using native build environment
+```
+
+  </TabItem>
+  <TabItem value={'arm'}>
 
-```bash {4}
+```bash
 # Create a new UrhoApp
 script/dockerized.sh arm rake new[ArmUrhoApp,demo]
 cd demo/ArmUrhoApp
 # Build the newly generated UrhoApp, specify other extra build options to target a specific ARM board
-URHO3D_HOME=/home/urho3d/stage-arm/usr/local script/dockerized.sh arm
+script/dockerized.sh arm
 ```
 
   </TabItem>
-  <TabItem value="linux">
+  <TabItem value={'linux'}>
 
 ```bash
 # Create a new UrhoApp
 script/dockerized.sh linux rake new[LinuxUrhoApp,demo]
 cd demo/LinuxUrhoApp
 # Build the newly generated UrhoApp
-URHO3D_HOME=/home/urho3d/stage-linux/usr/local script/dockerized.sh linux
+script/dockerized.sh linux
 ```
 
   </TabItem>
-  <TabItem value="rpi">
+  <TabItem value={'rpi'}>
 
-```bash {4}
+```bash
 # Create a new UrhoApp
 script/dockerized.sh rpi rake new[PiUrhoApp,demo]
 cd demo/PiUrhoApp
 # Build the newly generated UrhoApp, modify the "RPI_ABI" build option accordingly
-RPI_ABI=RPI4 URHO3D_HOME=/home/urho3d/stage-rpi/usr/local script/dockerized.sh rpi
+RPI_ABI=RPI4 script/dockerized.sh rpi
 ```
 
   </TabItem>
-  <TabItem value="web">
+  <TabItem value={'web'}>
 
 ```bash
 # Create a new UrhoApp
 script/dockerized.sh web rake new[WebUrhoApp,demo]
 cd demo/WebUrhoApp
 # Build the newly generated UrhoApp
-URHO3D_HOME=/home/urho3d/stage-web/usr/local script/dockerized.sh web
+script/dockerized.sh web
 ```
 
   </TabItem>
-  <TabItem value="win">
+  <TabItem value={'win'}>
 
 ```bash
 # Create a new UrhoApp
 script/dockerized.sh mingw rake new[WindowsUrhoApp,demo]
 cd demo/WindowsUrhoApp
 # Build the newly generated UrhoApp
-URHO3D_HOME=/home/urho3d/stage-mingw/usr/local script/dockerized.sh mingw
+script/dockerized.sh mingw
 ```
 
   </TabItem>
@@ -211,7 +232,7 @@ This is not a copy/paste error. You can build your new UrhoApp exactly the same
 
 :::
 
-The `URHO3D_HOME` build option tells the build system where to find the installed Urho3D library, if the installed location is not a system wide standard location. See the Build Options section for more information. The Maven local repository for Android platform is one of such standard location and hence the command for building UrhoApp on Android platform can be simplified.
+You can pass optional build options to the build system by using environment variables. One easy way to do that is to set them just in time on the same line before the actual command to be invoked. For example, `RPI_ABI=RPI4 script/dockerized.sh rpi`. See the Build Options section for more information.
 
 <div className={'text--center'}>
   <img src={'/img/docs/quick-start-screencast.svg'} alt={'Screencast'}/>
@@ -219,55 +240,56 @@ The `URHO3D_HOME` build option tells the build system where to find the installe
 
 ## UrhoApp Project Structure
 
-In order to reuse the same build system for Urho3D project to successfully build your own UrhoApp project, the UrhoApp project must be structured similarly to Urho3D project. Assuming you chose to use the `rake new` to create the UrhoApp project, you will have the following project structure under a new app directory in the specified parent directory:
+In order to reuse the same build system for Urho3D project to successfully build your own UrhoApp project, the UrhoApp project must be structured similarly to Urho3D project. Assuming you chose to use the `rake new` to create the UrhoApp project, you will have the following project structure under a new app directory:
 
 ```
 UrhoApp
-├── app
-│   ├── build.gradle.kts
-│   ├── CMakeLists.txt
-│   ├── proguard-rules.pro
-│   └── src
-│       ├─ cpp
-│       │  ├─ UrhoApp.cpp
-│       │  └─ UrhoApp.h
-│       ├─ java/io/urho3d/urhoapp
-│       │  └─ MainActivity.kt
-│       ├─ res
-│       |  └─ (truncated)
-│       └─ AndroidManifest.xml
-├── bin
-│   ├── CoreData
-│   │   └─ (as in Urho3D)
-│   └── Data
-│       ├─ Materials
-│       │  └─ Mushroom.xml
-│       ├─ Models
-│       │  └─ Mushroom.mdl
-│       ├─ Music
-│       │  └─ Ninja Gods.ogg
-│       └─ Textures
-│          ├─ Mushroom.dds
-│          ├─ UrhoIcon.icns
-│          └─ UrhoIcon.png
-├── build.gradle.kts
-├── cmake
-│   └── (as in Urho3D)
-├── CMakeLists.txt
-├── gradle/wrapper
-│   ├── gradle-wrapper.jar
-│   └── gradle-wrapper.properties
-├── gradle.properties
-├── gradlew
-├── gradlew.bat
-├── rakefile
-├── scripts
-│   └── (as in Urho3D)
-├── settings.gradle.kts
-├── .clang-format
-├── .clang-tidy
-├── .gitattributes
-└── .gitignore
+├─ app
+│  ├─ build.gradle.kts
+│  ├─ CMakeLists.txt
+│  ├─ proguard-rules.pro
+│  └─ src
+│     ├─ cpp
+│     │  ├─ UrhoApp.cpp
+│     │  └─ UrhoApp.h
+│     ├─ java
+│     │  └─ io/urho3d/urhoapp
+│     │     └─ MainActivity.kt
+│     ├─ res
+│     |  └─ (truncated)
+│     └─ AndroidManifest.xml
+├─ bin
+│  ├─ CoreData
+│  │  └─ (as in Urho3D)
+│  └─ Data
+│     ├─ Materials
+│     │  └─ Mushroom.xml
+│     ├─ Models
+│     │  └─ Mushroom.mdl
+│     ├─ Music
+│     │  └─ Ninja Gods.ogg
+│     └─ Textures
+│        ├─ Mushroom.dds
+│        ├─ UrhoIcon.icns
+│        └─ UrhoIcon.png
+├─ build.gradle.kts
+├─ cmake
+│  └─ (as in Urho3D)
+├─ CMakeLists.txt
+├─ gradle/wrapper
+│  ├─ gradle-wrapper.jar
+│  └─ gradle-wrapper.properties
+├─ gradle.properties
+├─ gradlew
+├─ gradlew.bat
+├─ rakefile
+├─ scripts
+│  └─ (as in Urho3D)
+├─ settings.gradle.kts
+├─ .clang-format
+├─ .clang-tidy
+├─ .gitattributes
+└─ .gitignore
 ```
 
 At the root of the project there are a few build scripts which can be grouped as follows:
@@ -282,12 +304,6 @@ All the above are for the build system, the actual meat of the UrhoApp project a
 - `app/` - mainly contains the C++ source code in `src/cpp/` and Kotlin/Java source code in `src/java/`.
 - `bin/` - contains the assets used by the Urho3D game engine, at the very least it should have `CoreData/` and `Data/`.
 
-:::tip
-
-The UrhoApp project can be opened directly in the IDE that supports CMake or Gradle build system, like **Android Studio**, **Clion**, **IntelliJ IDEA**, and **Visual Studio**. For other IDEs, like Xcode, use CMake to generate the initial build tree first.
-
-:::
-
 :::info
 
 The UrhoApp project is cross-platform out of the box!