From da4c7e7ed675c3bf405668739c3012d140856109 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 15 May 2024 05:34:42 +0200 Subject: Adding upstream version 126.0. Signed-off-by: Daniel Baumann --- browser/installer/windows/docs/FullInstaller.rst | 2 + browser/installer/windows/docs/NSISPlugins.rst | 101 +++++++++++++++++++++ browser/installer/windows/docs/newProjectDllVS.png | Bin 0 -> 27399 bytes .../windows/docs/projectPropertyPageVS.png | Bin 0 -> 258168 bytes .../windows/docs/projectSettingsDllVS.png | Bin 0 -> 144260 bytes 5 files changed, 103 insertions(+) create mode 100644 browser/installer/windows/docs/NSISPlugins.rst create mode 100644 browser/installer/windows/docs/newProjectDllVS.png create mode 100644 browser/installer/windows/docs/projectPropertyPageVS.png create mode 100644 browser/installer/windows/docs/projectSettingsDllVS.png (limited to 'browser/installer/windows/docs') diff --git a/browser/installer/windows/docs/FullInstaller.rst b/browser/installer/windows/docs/FullInstaller.rst index fcfa60371e..74e6ad047c 100644 --- a/browser/installer/windows/docs/FullInstaller.rst +++ b/browser/installer/windows/docs/FullInstaller.rst @@ -10,5 +10,7 @@ If it was not launched by the :doc:`StubInstaller`, an :ref:`Install Ping` is se The installer writes ``installation_telemetry.json`` to the install location, this is read by Firefox in order to send a telemetry event, see the event definition in `Events.yaml `_ (category ``installation``, event name ``first_seen``) for a description of the properties. There is also an ``install_timestamp`` property, which is saved in the profile to determine whether there has been a new installation; this is not sent as part of the ping. +The full installer can also access NSIS plugins written in C++, see :doc:`building NSIS plugins ` for more information. + .. toctree:: FullConfig diff --git a/browser/installer/windows/docs/NSISPlugins.rst b/browser/installer/windows/docs/NSISPlugins.rst new file mode 100644 index 0000000000..77b766999f --- /dev/null +++ b/browser/installer/windows/docs/NSISPlugins.rst @@ -0,0 +1,101 @@ +===================== +Building NSIS Plugins +===================== + +.. note:: + + This guide assumes that you have a Firefox build environment set up as well as a recent version of Visual Studio. The steps here use Visual Studio 2022. + +Instructions +------------ + +1. Make sure you are configured to build DLLs. Follow this `guide `_. +2. NSIS plugins are not integrated with the build system pending `bug 1771192 `_. You will need to build them manually by creating a new Visual Studio project in the ``$SRCDIR/other-licenses/nsis/Contrib/`` directory with the following settings. + +.. image:: newProjectDllVS.png +.. image:: projectSettingsDllVS.png + +3. Once the project has been created, right click on it in the sidebar and go to ``Configuration Properties -> C/C++ -> Precompiled Header`` and set ``Precompiled Header`` to "Not Using Precompiled Headers". + +.. image:: projectPropertyPageVS.png + +4. For easier testing set the output directory in ``Configuration Properties -> General`` to ``$SRCDIR/other-licenses/nsis/Plugins``. + +5. Delete any files generated when you created the Visual Studio project such as ``pch.h`` or ``framework.h`` and any related include statements. + +6. Download the source code for `NSIS version 3.07 `_. (current at the time of writing although possibly subject to change) and extract the source files. Navigate to ``Contrib/ExDLL`` and copy ``pluginapi.h``, ``pluginapi.c`` and ``nsis_tchar.h`` to where header files for your Visual Studio project live. Add them to your project. + +7. You can use the following template to get started with your own plugin: + +.. code:: cpp + + /* This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, you can obtain one at http://mozilla.org/MPL/2.0/. */ + + // Put a brief description of your NSIS plugin here. + + // Put your include statements here. + #include + #include "pluginapi.h" // This is taken from the NSIS plugin page + #include "myheader.h" + + // A struct used for reading the stack passed in to the function + struct stack_t { + stack_t* next; + TCHAR text[MAX_PATH]; + }; + + /** + * + * + * Put any additional functions you write here. + * + * + */ + + // I use popstringn and pushstringn from the NSIS pluginapi.h file. + + // This is the function I want to call from within NSIS + extern "C" void __declspec(dllexport) + MyNSISFunction(HWND, int string_size, TCHAR* variables, stack_t** stacktop, void*) { + wchar_t getArg[MAX_PATH+1]; + EXDLL_INIT(); + bool rv = false; + int popRet = popstringn(getArg, MAX_PATH+1); + if (popRet == 0) { + rv = FunctionThatTakesAnArgument(getArg); + } + pushstring(rv ? L"1" : L"0"); + } + + BOOL APIENTRY + DllMain(HMODULE, DWORD, LPVOID) { + return TRUE; + } + +8. Modify ``$SRCDIR/toolkit/mozapps/installer/windows/nsis/makensis.mk`` as follows: + +.. code:: text + + CUSTOM_NSIS_PLUGINS = \ + ... \ + MyPlugin.dll \ + ... \ + $(NULL) + + +9. **NSIS only works with 32-bit plugins so ensure your Visual Studio build configuration is set to x86.** Compile your new plugin. ``exp`` and ``lib`` files will also be generated but they can safely be deleted. + +10. The plugin can now be called from within NSIS as follows: + +.. code:: text + + MyPlugin::MyNSISFunc "$myNSISarg" + +.. note:: + + - You may need to run ``./mach clobber`` for your DLL to be recognized. + - You can compile your plugin in debug mode and step through it with a debugger by attaching to the installer/uninstall process. + - If libraries are needed, files in the ``$SRCDIR/mfbt/`` and ``$SRCDIR/toolkit/`` directories are usually okay although there may be exceptions. + - The best way to access headers is usually to simply copy them into the project given how disconnected this is from the rest of the build system. diff --git a/browser/installer/windows/docs/newProjectDllVS.png b/browser/installer/windows/docs/newProjectDllVS.png new file mode 100644 index 0000000000..fe82d3e03a Binary files /dev/null and b/browser/installer/windows/docs/newProjectDllVS.png differ diff --git a/browser/installer/windows/docs/projectPropertyPageVS.png b/browser/installer/windows/docs/projectPropertyPageVS.png new file mode 100644 index 0000000000..3d1ecb6083 Binary files /dev/null and b/browser/installer/windows/docs/projectPropertyPageVS.png differ diff --git a/browser/installer/windows/docs/projectSettingsDllVS.png b/browser/installer/windows/docs/projectSettingsDllVS.png new file mode 100644 index 0000000000..59329df681 Binary files /dev/null and b/browser/installer/windows/docs/projectSettingsDllVS.png differ -- cgit v1.2.3