Add build instructions

Co-authored-by: (x*ln(7))⁻¹ <[email protected]>
sandboxie-plus · Jan 10, 2024 · 9e05ab9 · 9e05ab9
1 parent 83876c1
commit 9e05ab9
Show file tree

Hide file tree

Showing 5 changed files with 84 additions and 11 deletions.
diff --git a/Installer/ReadMe.md b/Installer/ReadMe.md
@@ -0,0 +1,13 @@
+## Sandboxie Plus installer instructions
+
+### To create Sbie Plus installer environment
+
+1) Install Inno Setup 6.2.2 (installer is located at https://jrsoftware.org/isdl.php#stable)
+
+> Note: this section requires additional steps to be completed, please open a new pull request.
+
+### To create the Sbie Plus installers
+
+The Sbie Plus installer ISS file is [Sandboxie-Plus.iss](Sandboxie-Plus.iss).
+
+> Note: this section requires steps to be completed, please open a new pull request.
diff --git a/Sandboxie/ReadMe.md b/Sandboxie/ReadMe.md
@@ -1,15 +1,28 @@
-## Sandboxie Build Instructions
+## Sandboxie Classic build instructions
 
-Please note: there is another [ReadMe.md](./install/ReadMe.md) file in the [\install](./install/) folder that explains how to create the Sandboxie installers.
+- Please note: there is another [ReadMe.md](./install/ReadMe.md) file in the [install](./install/) folder that explains how to create the Sandboxie Classic installers.
+- Please note: the following instructions may lag behind the [CI workflow](../.github/workflows/main.yml), so be aware of any version change.
 
-1) Sandboxie builds under MS Visual Studio 2019.
-2) Install the Windows Driver Kit (WDK) for Windows 10, version 2004:
+Sandboxie Classic builds under Visual Studio 2019, as it offers the widest compatibility range, allowing us to build a driver which works with Windows 7 up to Windows 11.
+
+1) Download [Visual Studio 2019](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products)
+2) In the Visual Studio Installer, tick _Desktop development with C++_
+	- This includes the Windows 10 SDK 10.0.19041
+3) The _MFC for latest v142 build tools {architecture}_ is also needed. Select it from the side panel or from the individual components tab
+4) If you need to build for other platforms, install the corresponding components
+	- _MSVC v142 - VS 2019 C++ {architecture} build tools (Latest)_
+	- _MFC for latest v142 build tools {architecture}_
+5) Install the Windows Driver Kit (WDK) for Windows 10, version 2004 (10.0.19041):
 	https://go.microsoft.com/fwlink/?linkid=2128854
-3) The VS Solution File, Sandbox.sln, is in the source code root. Open this SLN in Visual Studio.
+6) The VS Solution File, Sandbox.sln, is in the source code root. Open this SLN in Visual Studio.
+7) If the WDK Extension doesn't install automatically, install it (can be found in <Windows Kits directory>\10\Vsix\VS2019)
+8) If you have a more recent Windows SDK version installed, retarget the solution to 10.0.19041
+	- This is for example necessary if VS 2022 is also installed with the default desktop C++ components
+9) To compile for x64, it's necessary to first compile `Solution/core/LowLevel` for Win32 (x86)
 
-### Source Projects (in alphabetical order)
+### Source projects (in alphabetical order)
 
-Note: the core of Sandboxie are the driver, SbieDrv, the service, SbieSvc, and the injection DLL, SbieDll. Study these projects first.
+> Note: the core of Sandboxie are the driver, SbieDrv, the service, SbieSvc, and the injection DLL, SbieDll. Study these projects first.
 
 [Common (\apps\common)](./apps/common). It builds common.lib, which contains some common GUI objects, and it is used by the Control and Start projects.
 
@@ -24,7 +37,7 @@ Note: the core of Sandboxie are the driver, SbieDrv, the service, SbieSvc, and t
 [SandboxCrypto (apps\com\Crypto)](./apps/com/Crypto). It creates SandboxieCrypto.exe.
 
 [SandboxieInstall (\install\release)](./install/release). It creates the combined x64/x86 installer SandboxieInstall.exe by combining the x64 & x86 installer binaries into a RC file.
-- Please note: SandboxieInstall is not built during the normal SLN build. It must be built manually after the x64 & x86 installers are completed.
+> Note: SandboxieInstall is not built during the normal SLN build. It must be built manually after the x64 & x86 installers are completed.
 
 [SandboxRpcSs (\apps\com\RpcSs)](./apps/com/RpcSs). It creates SandboxieRpcSs.exe, the Sbie's wrapper for the Remote Procedure Call Sub-System.
 

diff --git a/Sandboxie/install/ReadMe.md b/Sandboxie/install/ReadMe.md
@@ -19,11 +19,12 @@
 
 Everything above only needs to be done once. Then your machine should be good to go.
 
-### To create the Sbie installers
+### To create the Sbie Classic installers
 
 The Sbie installer NSI file is [\install\SandboxieVS.nsi](../install/SandboxieVS.nsi).
 
-Note: the following procedure is only valid for the old code signing not mediated by Microsoft, please refer to issue [#1248](https://github.com/sandboxie-plus/Sandboxie/issues/1248).
+> Note: this section contains obsolete information, as it is only valid for the old code signing not mediated by Microsoft.
+> Please refer to issue [#1248](https://github.com/sandboxie-plus/Sandboxie/issues/1248) and open a new pull request to update the following steps:
 
 1) Sign the binaries (if applicable).
 2) Set the #defines in [\common\my_version.h](../common/my_version.h) (SBIE_INSTALLER_PATH, etc.) to the location of your binaries. (These #defines are read by SandboxieVS.nsi).

diff --git a/SandboxiePlus/ReadMe.md b/SandboxiePlus/ReadMe.md
@@ -0,0 +1,46 @@
+## Sandboxie Plus build instructions
+
+- Please note: there is another [ReadMe.md](../Installer/ReadMe.md) file that explains how to create the Sandboxie Plus installers.
+- Please note: the following instructions may lag behind the [CI workflow](../.github/workflows/main.yml), so be aware of any version change.
+
+Sandboxie Plus builds under Visual Studio 2019, as it offers the widest compatibility range, allowing us to build a driver which works with Windows 7 up to Windows 11.
+
+1) We will be installing Visual Studio Community Edition which is sufficient for our purposes, during the installation we need to take care of selecting a Windows SDK version which matches the WDK version we will be installing in the next step.
+	- If you have VS 2019 already installed, you can open the installer and check which SDK you have and add if necessary one matching the WDK.
+2) Next, we will install WDK 20xxx which is required to build the driver, the WDK installer installs the required VS plugin at the end.
+3) So far so good, at this point we already have all we need to build Sandboxie Classic. To build the SandMan UI of Sandboxie Plus, though, we also need the Qt Framework, we can use either 5.15.2 or 6.3.x, but since Qt 6.x does not support Windows 7 without custom patches to base components, we will stick with Qt 5.15.2 for this tutorial.
+	- Note: however, if you want to build SandMan UI for ARM64, you will need to use Qt 6.3.x or later.
+4) We use Qt's online installer and select all required components. I like to also install the source and debug information, but this is just for convenience when debugging and not needed for the build process.
+5) Last but not least, we have to install the VS extension for Qt and configure it to point to our Qt installation.
+6) Ok, now we are ready to build, we start with Sandboxie Classic, we open the Sandbox.sln, select our platform and build type, and run the build.
+	- If we build for x64, we will need to also build the SbieSvc and SbieDll for 32-bit.
+	- If we were building for ARM64, we would also need the ARM64EC version of SbieDll.
+7) And now we continue with building the SandMan UI to create Sandboxie Plus. Here we open the Sandboxie-Plus.sln, select our platform and build type, and run the build.
+8) Once that is done, we only need to combine the two and here it is: Sandboxie Plus is ready for service.
+
+At this point, you may wonder how to run this build. In the end, the driver is not signed and we did not touch the process of signing the user mode components either.
+
+As signing the driver is probably not feasible for most developers due to the lack of an EV code signing certificate, we will set up our Windows to run in test mode by entering "bcdedit /set testsigning on" in an elevated command prompt and rebooting. Once rebooted, we can start the SandMan UI and use the Maintenance menu to install all components, start and connect them with only one click.
+
+You may notice that we did not get the obligatory "access denied" error we would expect by connecting an unsigned user mode component to the driver. This is because when the driver sees Windows being run in test mode, it also disables the custom signature verification mechanism, meaning you don't need to create any *.sig files for your own Sandboxie Plus test build.
+
+With everything running, you can now go to the Global Settings and enter your supporter certificate to unlock all the exclusive Plus features.
+
+### Source projects
+
+> Note: the core of Sandboxie are the driver, SbieDrv, the service, SbieSvc, and the injection DLL, SbieDll:
+[Sandboxie\ReadMe.md#source-projects-in-alphabetical-order](../Sandboxie/ReadMe.md#source-projects-in-alphabetical-order)
+
+Sandboxie Plus is made up of the following components:
+
+[MiscHelpers (\MiscHelpers)](./MiscHelpers)
+
+[QSbieAPI (\QSbieAPI)](./QSbieAPI)
+
+[QtSingleApp (\QtSingleApp)](./QtSingleApp)
+
+[SandMan (\SandMan)](./SandMan)
+
+[SbieShell (\SbieShell)](./SbieShell)
+
+[UGlobalHotkey (\UGlobalHotkey)](./UGlobalHotkey)
diff --git a/SandboxiePlus/SandMan/SandMan.vcxproj b/SandboxiePlus/SandMan/SandMan.vcxproj
@@ -127,7 +127,7 @@
   </PropertyGroup>
   <PropertyGroup Label="QtSettings" Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
     <QtInstall>msvc2019_64</QtInstall>
-    <QtModules>core;gui;network;qml;widgets;concurrent;widgets-private;qml-private</QtModules>
+    <QtModules>core;network;gui;widgets;qml;winextras;concurrent;widgets-private;qml-private</QtModules>
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|ARM64'" Label="QtSettings">
     <QtInstall>msvc2019_64</QtInstall>