Merge branch 'feature/cef-sandbox' into 'master'

MacOS, Dev Script Overhaul and Sandbox

See merge request voltstro-studios/uwb/unitywebbrowser!3

.gitignore

@@ -385,4 +385,5 @@ FodyWeavers.xsd
 *.sln.iml
 
 # MacOS
-*.DS_Store
+*.DS_Store
+

docs/README.md

@@ -0,0 +1,22 @@
+# UnityWebBrowser Docs
+
+UnityWebBrowser's docs are built from here.
+
+UWB docs are generated using [DocFx](https://dotnet.github.io/docfx/). See the DocFx site for setup of the tool.
+
+## Building Locally
+
+```
+docfx metadata
+docfx build
+```
+
+To preview locally, use:
+
+```
+docfx serve _site/
+```
+
+## Publishing
+
+The [publicly hosted docs](https://projects.voltstro.dev/UnityWebBrowser/latest/) are automatically published using [VoltProjects](https://github.com/Voltstro/VoltProjects).

docs/articles/dev/dev-guide.md

@@ -7,6 +7,14 @@ This section contains docs useful for developers who want to work on UWB's code.
 >   - Advance Unity Knowledge
 >   - Advance C# & .NET Knowledge
 
-To get going, see the [setup section](setup.md).
+## Repo Setup
 
-When developing for UWB, it is highly recommended to develop using `UnityWebBrowser.UnityProject` provided in the repo. Other means of development will **NOT** be supported! Even if you are creating an external separate package for UWB, it is still recommended to develop using the provided project in the repo! We recommend this approach as the Unity project has all dependencies ready to go, all the tools, and proper projects setup for the code (both Engine and Core).
+To setup UWB's git repo, see the [setup section](setup.md).
+
+## Developing
+
+When developing for UWB, it is highly recommended to develop using the `src/UnityWebBrowser.UnityProject` project provided in the repo. Other means of development will **NOT** be supported! Even if you are creating an external separate package for UWB, it is still recommended to develop using the provided project in the repo! We recommend this approach as the Unity project has all dependencies ready to go, all the tools, and proper projects setup for the code (both Engine and Core).
+
+## Packaging
+
+TODO

docs/articles/dev/dev-scripts.md

@@ -0,0 +1,22 @@
+# Dev Scripts
+
+UWB contains all of its dev scripts in `src/DevScripts/`. Dev scripts are used for automating tasks like downloading external files or building projects.
+
+## Usage
+
+There are three main scripts you will want to use.
+
+1. `download_cef_<platform>.py`
+   - Used for downloading the required version of CEF and extracting it.
+2. `build_cef_<platform>.py`
+   - Builds the `UnityWebBrowser.Engine.Cef` project in publish mode and outputs the built files into `src/Packages/UnityWebBrowser.Engine.Cef.<Platform>/Engine~/`. Needs to be ran if the CEF engine project has any changes made to it.
+3. `build_shared.py`
+   - Builds the `VoltstroStudios.UnityWebBrowser.Shared` project in `ReleaseUnity` configuration mode, which will place the built files into `src/Packages/UnityWebBrowser/Plugins`. Needs to be ran if the shared project has any changes made to it.
+
+## Base Scripts
+
+There are a couple of scripts with `_base` in it's name. These scripts are shared modules that are used by the scripts that the user executes.
+
+## Why Python
+
+In older versions of UWB, we used PowerShell as the language of choice for our dev scripts. PowerShell has one main advantage, its cross-platform. But so is Python. Python's runtime also includes a lot of useful utilities like archive extraction. While in PowerShell technically this is possible (you can call .NET methods), its a bit of a pain to do.

docs/articles/dev/project-layout.md

@@ -27,7 +27,7 @@ src/
 
 - `docs/`, `media/` and `src/` are all fairly explanatory.
 
-- `DevScripts/` and `DevTools/` provide developer scripts and other external applications that are needed.
+- `DevScripts/` provide developer scripts that are used for automating certain tasks while developing UWB.
 
 - `Imports/` contains shared `.targets` and `.props` files that are used by the .NET projects.
 
@@ -43,11 +43,11 @@ Quick description of all the individual projects.
 
 ### UnityWebBrowser.UnityProject
 
-This is the provided Unity project that can be used for UWB development. It has all of UWB's packages included locally.
+This is the provided Unity project that can be used for UWB development. It has all of UWB's packages included locally. It uses the lowest Unity version that UWB supports (Unity 2021.3.x).
 
 ### UnityWebBrowser.Pages
 
-NodeJs/Yarn project that used to build out HTML that engines use for internal pages.
+NodeJs/Yarn project that is used to build out HTML files that engines use for internal pages.
 
 ### VoltstroStudios.UnityWebBrowser.Shared
 
@@ -59,4 +59,4 @@ NodeJs/Yarn project that used to build out HTML that engines use for internal pa
 
 ### UnityWebBrowser.Engine.Cef
 
-UWB's CEF Engine. .NET project that is built out as an application. In publish mode it will build the app into a single file.
+UWB's CEF Engine. .NET project that is built out as an application. Is compiled using .NET's [NativeAOT deployment](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/) mode.

docs/articles/dev/setup.md

@@ -8,12 +8,12 @@ These prerequisites are **mandatory** to compile UWB.
 
 ```
 Unity 2021.3.x
-.NET 8 SDK
-PowerShell (formally PowerShell Core)*
+.NET 8 SDK (With NativeAOT)
+Python 3
 Git
 ```
 
-*[Modern PowerShell](https://github.com/powershell/powershell#get-powershell) is required! The one built into Windows does **NOT** work.
+UWB compiles engines using .NET's [NativeAOT deployment mode](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/). NativeAOT it self has some prerequisites, please [see the docs for what you will need](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot/?tabs=net8plus%2Cwindows#prerequisites).
 
 ### Additional Optional Prerequisites
 
@@ -42,20 +42,15 @@ git clone --recursive https://github.com/Voltstro-Studios/UnityWebBrowser.git
 > git submodule update
 > ```
 
-Once you have the repo cloned with the submodules, you must now run the `src/setup-all.ps1` script with PowerShell.
+Once you have the repo cloned with submodules, you can run the inital setup script.
 
-You can go into PowerShell with the command:
-
-```shell
-pwsh
 ```
-
-Once in PowerShell, go to the `src/` directory, and run the `setup-all.ps1` script:
-
-```powershell
-./setup-all.ps1
+python src/DevScripts/setup_all.py
 ```
 
+> [!NOTE]
+> On some platforms, you may need to run python using `python3` instead of just `python`.
+
 Depending on your system, and your download speeds, this script could take upto a minute or even longer. You only need to run the setup script once.
 
 You can now open up the `src/UnityWebBrowser.UnityProject` project with Unity.
@@ -88,7 +83,4 @@ You can open `src/UnityWebBrowser.sln` with your preferred IDE. The rest of the
 
 ## Dev Scripts
 
-There a many dev scripts in the `src/DevScripts` directory. The main ones that you will most likely use are:
-
-- `download-cef-<OS>.ps1`
-- `publish-<Section>-<OS>.ps1`
+There are many DevScripts which you may need to use. For details on what dev scripts does what, see [Dev Scripts](dev-scripts.md).

docs/articles/toc.yml

@@ -27,6 +27,8 @@
       href: dev/dev-guide.md
     - name: Setup
       href: dev/setup.md
+    - name: Dev Scripts
+      href: dev/dev-scripts.md
     - name: How Things Work
       href: dev/how-things-work.md
     - name: Project Layout

docs/docfx.json

@@ -7,6 +7,9 @@
                     "src": "../src/Packages/UnityWebBrowser",
                     "files": [
                         "**/*.cs"
+                    ],
+                    "exclude": [
+                        "Samples~/**"
                     ]
                 },
                 {
@@ -67,7 +70,8 @@
         ],
         "xref": [
             "https://github.com/dotnet/docfx/raw/main/.xrefmap.json",
-            "https://normanderwan.github.io/UnityXrefMaps/2021.3/xrefmap.yml"
+            "https://voltstro-studios.gitlab.io/UnityDocs/UnityXrefMaps/2021.3/xrefmap.yml",
+            "https://voltstro-studios.gitlab.io/UnityDocs/UnityXrefMaps/pkgs/com.unity.ugui@1.0/xrefmap.yml"
         ],
         "dest": "_site"
     }

src/DevScripts/build_base.py

@@ -0,0 +1,30 @@
+import subprocess
+import os
+
+package_rid_mapping = {
+    'win-x64': 'Win-x64',
+    'linux-x64': 'Linux-x64'
+}
+
+def build_cef_engine(platform: str) -> None:
+    """
+    Base CEF engine build for Windows and Linux
+    """
+    if platform not in package_rid_mapping:
+        raise Exception('Platform {0} is not valid!'.format(platform))
+
+    platform_folder = package_rid_mapping[platform]
+
+    cef_project_path = os.path.abspath(os.path.join(__file__, '../../UnityWebBrowser.Engine.Cef/Main/UnityWebBrowser.Engine.Cef.csproj'))
+    cef_publish_path = os.path.abspath(os.path.join(__file__, '../../Packages/UnityWebBrowser.Engine.Cef.{0}/Engine~'.format(platform_folder)))
+
+    print('Build CEF project \'{0}\' to \'{1}\''.format(cef_project_path, cef_publish_path))
+
+    subprocess.run(['dotnet', 'publish', cef_project_path, '-r=' + platform, '-p:PublishDir=' + cef_publish_path, '--nologo'])
+
+
+def build_project(project: str) -> None:
+    project_path = os.path.abspath(os.path.join(__file__, '../../{0}/{0}.csproj'.format(project)))
+
+    subprocess.run(['dotnet', 'build', project_path, '-c=ReleaseUnity'])
+

src/DevScripts/build_base_macos.py

@@ -0,0 +1,79 @@
+import subprocess
+import shutil
+import os
+
+def build_cef_engine_macos(arch) -> None:
+    """
+    MacOS custom build script.
+
+    MacOS needs a custom build process because of the .plist files and specific folder layout the build needs to be in
+    """
+
+    # Project path
+    cef_engine_path = os.path.abspath(os.path.join(__file__, '../../UnityWebBrowser.Engine.Cef/Main'))
+    cef_engine_subprocess_path = os.path.abspath(os.path.join(__file__, '../../UnityWebBrowser.Engine.Cef/SubProcess'))
+    cef_engine_macos_path = os.path.abspath(os.path.join(__file__, '../../Packages/UnityWebBrowser.Engine.Cef.MacOS-{0}/Engine~/'.format(arch)))
+
+    # Delete build dir
+    cef_engine_build_path = os.path.abspath(os.path.join(__file__, '../../UnityWebBrowser.Engine.Cef/bin/Release/publish/osx-{0}/'.format(arch)))
+    if os.path.exists(cef_engine_build_path):
+        shutil.rmtree(cef_engine_build_path)
+
+    # First, build main CEF engine project
+    print('Building CEF Engine from {0}'.format(cef_engine_path))
+    subprocess.run(['dotnet', 'publish', '-r=osx-{0}'.format(arch), '-c=Release'], cwd=cef_engine_path)
+
+    # Build SubProcess
+    print('Building CEF Engine SubProcess from {0}'.format(cef_engine_subprocess_path))
+    subprocess.run(['dotnet', 'publish', '-r=osx-{0}'.format(arch), '-c=Release'], cwd=cef_engine_subprocess_path)
+
+    cef_framework_path = os.path.abspath(os.path.join(__file__, '../../ThirdParty/Libs/cef/macos{0}/Release/Chromium Embedded Framework.framework'.format(arch)))
+
+    cef_engine_app_path = os.path.join(cef_engine_build_path, 'UnityWebBrowser.Engine.Cef.app')
+    cef_engine_app_contents_path = os.path.join(cef_engine_app_path, 'Contents')
+    cef_engine_app_macos_path = os.path.join(cef_engine_app_contents_path, 'MacOS')
+    cef_engine_app_resources_path = os.path.join(cef_engine_app_contents_path, 'Resources')
+    cef_engine_app_frameworks_path = os.path.join(cef_engine_app_contents_path, 'Frameworks/')
+
+    os.makedirs(cef_engine_app_macos_path, exist_ok=True)
+    os.makedirs(cef_engine_app_resources_path, exist_ok=True)
+    os.makedirs(cef_engine_app_frameworks_path, exist_ok=True)
+
+    shutil.copy(os.path.join(cef_engine_build_path, 'UnityWebBrowser.Engine.Cef'), cef_engine_app_macos_path)
+    shutil.copy(os.path.join(cef_engine_build_path, 'info.plist'), cef_engine_app_contents_path)
+    shutil.copy(os.path.join(cef_engine_build_path, 'icon.icns'), cef_engine_app_resources_path)
+    shutil.copytree(cef_framework_path, os.path.join(cef_engine_app_frameworks_path, 'Chromium Embedded Framework.framework'))
+
+    # Copy the many different helper apps needed
+    subprocess_types = [
+        None,
+        'GPU',
+        'Plugin',
+        'Renderer'
+    ]
+
+    for type in subprocess_types:
+        if not type:
+            name = ''
+            plist_file = 'info-subprocess.plist'
+        else:
+            name = ' ({0})'.format(type)
+            plist_file = 'info-subprocess-{0}.plist'.format(type.lower())
+
+        bundle_name = 'UnityWebBrowser.Engine.Cef.SubProcess{0}.app/Contents'.format(name)
+        cef_engine_subprocess_app_path = os.path.join(cef_engine_app_frameworks_path, bundle_name)
+        cef_engine_subprocess_macos_path = os.path.join(cef_engine_subprocess_app_path, 'MacOS')
+
+        os.makedirs(cef_engine_subprocess_macos_path, exist_ok=True)
+        shutil.copy(os.path.join(cef_engine_build_path, plist_file), os.path.join(cef_engine_subprocess_app_path, 'info.plist'))
+        shutil.copy(os.path.join(cef_engine_build_path, 'UnityWebBrowser.Engine.Cef.SubProcess'), os.path.join(cef_engine_subprocess_macos_path, 'UnityWebBrowser.Engine.Cef.SubProcess{0}'.format(name)))
+
+    # Copy final app bundle to MacOS package
+    if not os.path.exists(cef_engine_macos_path):
+        os.makedirs(cef_engine_macos_path, exist_ok=True)
+
+    cef_app_final_path = os.path.join(cef_engine_macos_path, 'UnityWebBrowser.Engine.Cef.app')
+    if os.path.exists(cef_app_final_path):
+        shutil.rmtree(cef_app_final_path)
+
+    shutil.copytree(cef_engine_app_path, cef_app_final_path)

src/DevScripts/build_cef_linux64.py

@@ -0,0 +1,3 @@
+from build_base import build_cef_engine
+
+build_cef_engine('linux-x64')

src/DevScripts/build_cef_macosarm64.py

@@ -0,0 +1,3 @@
+from build_base_macos import build_cef_engine_macos
+
+build_cef_engine_macos('arm64')

src/DevScripts/build_cef_macosx64.py

@@ -0,0 +1,3 @@
+from build_base_macos import build_cef_engine_macos
+
+build_cef_engine_macos('x64')

src/DevScripts/build_cef_windows64.py

@@ -0,0 +1,3 @@
+from build_base import build_cef_engine
+
+build_cef_engine('win-x64')

src/DevScripts/build_shared.py

@@ -0,0 +1,4 @@
+
+from build_base import build_project
+
+build_project('VoltstroStudios.UnityWebBrowser.Shared')