Updated readme with build script changes

Author: bernerdad

README.md

@@ -1,19 +1,10 @@
 # Windscribe 2.0 Desktop Application
 This repo contains the complete source code for the Windscribe 2.0 app. This includes installer, service/helper, backend process and GUI. 
-Please note that this is a work-in-progress, your mileage may vary.
-
-## Build the Windscribe 2.0 app
-
-See below for environement and library prerequisites to build the application on each system.
-
-Simply run `tools/build_all` for an unsigned build. See `build_all --help` for other build options. A successfully build script will place the installer in the `build-exe` directory.  Note that an unsigned build is required to connect the VPN when building without code signing.
-
 
 ## Windows
 ### Prerequisites
 
 - Windows 10.
-- Recommended 120+ GB of storage.
 - Install git (https://git-scm.com/downloads). When installing Git, you can stick with all the default options presented to you by the installer.
 - Clone the repository.
 - Visual Studio Community 2017 (run install_vs.bat with admin rights from /common/prepare_build_environment/windows).
@@ -36,92 +27,101 @@ Simply run `tools/build_all` for an unsigned build. See `build_all --help` for o
 - python tools/bin/get-pip.py
 - python -m pip install -r tools/requirements.txt
 
-### Install signing certificate
+### Install signing certificate (optional)
 - Copy your PFX code signing file to installer/windows/signing/code_signing.pfx.
 - Edit tools/build_all.yml and enter the password for your PFX file in the password_cert field of the windows_signing_cert section.
-- Note that the application will still build and run without these signatures, but using the VPN without signatures will require a debug build.
+- Edit common/utils/executable_signature/executable_signature_defs.h and set the WINDOWS_CERT_SUBJECT_NAME entry to match your certficate's name of signer field.
 
 ### Build libraries
 
 Go to subfolder tools/deps and run the following scripts in order. Libraries will be placed in build-libs.
 
-1. install_jom 
-2. install_openssl
-3. install_qt
-4. install_cares
-5. install_zlib
-6. install_curl
-7. install_boost
-8. install_lzo
-9. install_openvpn
-10. install_wireguard
-11. install_stunnel
-12. install_protobuf
+- install_jom 
+- install_openssl
+- install_qt
+- install_cares
+- install_zlib
+- install_curl
+- install_boost
+- install_lzo
+- install_openvpn
+- install_wireguard
+- install_stunnel
+- install_protobuf
 
 #### Notes
 - Some libraries depends on others. Jom is installed first and speeds up further builds. Almost all of the libraries depends on openssl. Openvpn depends on LZO. Curl depends on openssl and zlib.
 - If you notice install or build scripts fail for seemingly no reason, try running each script from a fresh shell instance (CMD or gitbash). It appears to have something to do with a character limit on PATH or ENV variables.
 
+### Build the Windscribe 2.0 app
 
+Go to subfolder tools and run 'build_all'. Assuming all goes well with the build, the installer will be placed in build-exe.  You can run 'build_all --sign' for a code-signed build, using the certificate from the 'Install signing certificate' section above, which will perform run-time signature verification checks on the executables.  Note that an unsigned build must be installed on your PC if you intend to debug the project using Qt Creator.
+
+See `build_all --help` for other build options.
+
+You will find the application logs in C:/Users/USER/AppData/Local/Windscribe/Windscribe2.
 
 ## Mac
 ### Prerequisites
 
 - MacOS Catalina or MacOS Big Sur (We recommend building/developing only on a native machine. VM setups are not well tested)
-- Recommended 120 GB of storage (Need to take a closer look at this number, we may be able to get away with as little as 80GB)
 - Install brew (brew.sh)
     - /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 - Install Xcode 11.3.1 if using MacOS Catalina, or Xcode 11.7 if using Big Sur
-    - Note: these downloads will require successful AppleID login:
+    - Note: these downloads will require you to first login to your Apple account.
     - https://download.developer.apple.com/Developer_Tools/Xcode_11.7/Xcode_11.7.xip
     - https://download.developer.apple.com/Developer_Tools/Xcode_11.3.1/Xcode_11.3.1.xip
     - The brew install step above will have installed the Xcode command-line tools.  Make sure to run Xcode after installing it, and set the Command Line Tools in Preferences->Locations to the version of Xcode you installed.
-
 - git (https://git-scm.com/downloads). This step is optional, as git is bundled with Xcode.
     - brew install git
 - Clone the repository.
-- Install Auto-Tools and 7-Zip (See below "Install Auto-Tools")
+- Install Auto-Tools and 7-Zip:
+    - brew install libtool
+    - brew install automake
+    - brew install p7zip
 - Install Wireguard build tools (brew install go)
 - Install CppCheck (brew install cppcheck)
-- Install dropDMG from: https://c-command.com/dropdmg/
-    - Create symlink for dropdmg
-        - ln -s /Applications/DropDMG.app/Contents/Frameworks/DropDMGFramework.framework/Versions/A/dropdmg /usr/local/bin/dropdmg
-    - Run the DropDMG app and accept the update command-line tools prompt
-    - Disable auto-update
-    - Enable "Quit when done" in Preferences->Advanced
-    - Copy desktop-v2/common/prepare_build_environment/mac/DropDMG/Configurations and Layouts into ~HOME/Library/Application Support/DropDMG/Configurations and Layouts
-- Install cmake (3.20.1 last tested) from: https://cmake.org/download/ 
+- Install dmgbuild:
+    - python -m pip install dmgbuild
+- Install cmake from: https://cmake.org/download/ 
 - Install python deps:
-  - python tools/bin/get-pip.py
-  - python -m pip install -r tools/requirements.txt
+    - python tools/bin/get-pip.py
+    - python -m pip install -r tools/requirements.txt
 
-### Set up code signing for release builds
-- Install your Developer ID signing certificate in the Keychain.
-- TBD...
-
-### Build Dependencies
-- Open a terminal in desktop-v2/tools/deps:
-- Run install_openssl
-- Run install_qt
-- Run install_cares
-- Run install_boost
-- Run install_curl
-- Run install_lzo
-- Run install_openvpn
-- Run install_wireguard
-- Run install_stunnel
-- Run install_protobuf
-- Run install_gtest
+### Install signing certificate (required)
+- Install your Developer ID Application signing certificate from your Apple Developer account in Keychain Access.
+- Edit common/utils/executable_signature/executable_signature_defs.h and set the MACOS_CERT_DEVELOPER_ID entry to match your Developer ID Application signing certificate.
+
+### Build libraries
+
+Go to subfolder tools/deps and run the following scripts in order. Libraries will be placed in build-libs.
+
+- install_openssl
+- install_qt
+- install_cares
+- install_boost
+- install_curl
+- install_lzo
+- install_openvpn
+- install_wireguard
+- install_stunnel
+- install_protobuf
+- install_gtest
 
 ### Notes on building libraries:
     - Some libraries depends on others. Almost all of the libraries depends on openssl. Openvpn depends on LZO.
-    - The install scripts put the dependencies in desktop-v2/build-libs.
 
+### Build the Windscribe 2.0 app
 
-### Install Auto-Tools and 7-Zip (via HomeBrew):
-    - brew install libtool
-    - brew install automake
-    - brew install p7zip
+Go to subfolder tools and run 'build_all'. Assuming all goes well with the build, the installer will be placed in build-exe.  You can run 'build_all --sign' for a production build which will perform run-time signature verification checks on the executables.  Note that an unsigned build must be installed on your Mac if you intend to debug the project using Qt Creator.
+
+See `build_all --help` for other build options.
+
+You will find the application logs in ~/Library/Application Support/Windscribe/Windscribe2.
+
+### Platform Notes:
+    - If you make any changes to the helper source code (backend/mac/helper/src), you must increase the CFBundleVersion in backend/mac/helper/src/helper-info.plist. The installer only updates the helper if this bundle version number has changed.
+    - The IKEv2 protocol will only function in builds produced by Windscribe.  It's implementation on MacOS utilizes the NEVPNManager API, which requires the 'Personal VPN' entitlement (com.apple.developer.networking.vpn.api) and an embedded provisioning profile file.  If you wish to enable IKEv2 functionality, you will have to create an embedded provisioning file in your Apple Developer account and use it in the engine project (See 'embedded.provisionprofile' in backend/engine/engine.pro).
 
 ## Linux
 ### Prerequisites
@@ -178,19 +178,26 @@ Build process tested on Ubuntu 16.04 (gcc 5.4.0) and Ubuntu 20.04/ZorinOS 16 (gc
   - python tools/bin/get-pip.py
   - python -m pip install -r tools/requirements.txt
 
-### Build Dependencies
-- Open a terminal in desktop-v2/tools/deps:
-- Run install_openssl
-- Run install_qt
-- Run install_cares
-- Run install_boost
-- Run install_curl
-- Run install_lzo
-- Run install_openvpn
-- Run install_wireguard
-- Run install_stunnel
-- Run install_protobuf
-- Run install_gtest
-
-### After building and installing
-The application installs to /usr/local/windscribe.  You will find the logs in ~/.local/share/Windscribe/Windscribe2.
+### Build libraries
+
+Go to subfolder tools/deps and run the following scripts in order. Libraries will be placed in build-libs.
+
+- install_openssl
+- install_qt
+- install_cares
+- install_boost
+- install_curl
+- install_lzo
+- install_openvpn
+- install_wireguard
+- install_stunnel
+- install_protobuf
+- install_gtest
+
+### Build the Windscribe 2.0 app
+
+Go to subfolder tools and run 'build_all'. Assuming all goes well with the build, the installer will be placed in build-exe.
+
+See `build_all --help` for other build options.
+
+The application installs to /usr/local/windscribe.  You will find the application logs in ~/.local/share/Windscribe/Windscribe2.