From a9edcfaa23bce182a0fb024a5a962813238d76ad Mon Sep 17 00:00:00 2001 From: denelon Date: Wed, 9 Mar 2022 13:08:44 -0800 Subject: [PATCH 01/14] Create #182 - Support for installation of portable standalone apps.md Draft for portable applications. --- ...nstallation of portable standalone apps.md | 188 ++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 doc/specs/#182 - Support for installation of portable standalone apps.md diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md new file mode 100644 index 0000000000..15261565cb --- /dev/null +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -0,0 +1,188 @@ +--- +author: Demitrius Nelon @denelonms +created on: 2022-03-09 +last updated: 2022-03-09 +issue id: 182 +--- + +# Portable/Standalone applications + +"For [#182](https://github.com/microsoft/winget-cli/issues/182)" + +## Abstract + +Several packages do not have an installer. They are simply a binary executable. This specification describes how these types of programs will be treated as "packages" by the Windows Package Manager. + +## Inspiration + +Just because an installer doesn't exist for a particular package, that doesn't mean you shouldn't be able to install it with the Windows Package Manager. + +## Solution Design + +The installer type “portable” will be added to the enumerated list of installer types to support these types of packages. + +When one of these packages is encountered there are several aspects to “installing” these packages and supporting the “upgrade” behavior. Notable concerns include the location of the package, creating or updating an entry in Windows Apps & Features. + +### Command Line Arguments + +Users should be able to specify the location for where the program is “installed” on their machine with the “--location” argument. + +Some packages like GitLab Runner have a file name including extra metadata (gitlab-runner-windows-386.exe). The installation instructions suggest renaming the file after it has been downloaded. In that vein, portable / standalone executables should have their “command” value specified so the Windows Package Manager can perform a default rename behavior. In addition, a “--rename” argument should be added so the user can choose a value they prefer. To have the upgrade scenario honor the custom name, this information should be recorded in the installed packages data store. + +Some portable applications generate or consume other files. An additional argument "--purge" will be added for the uninstall scenario to remove all files and subsequently the directory if the user wishes. The corrolary "--preserve" will be used to preserve files if the default setting has been modified. + +### Settings + +Users should have settings to be able to specify a new default location other than the system default for the Windows Package Manager. + +The default path for installing these packages is "%LOCALAPPDATA%/WinGet_Packages/User" for user based installs. The default path for installing these packages is "%LOCALAPPDATA%/WinGet_Packages/Machine"for machine wide installs. + +The corresponding settings are "PortablePackageUserRoot" and "PortablePackageUserRoot". + +>Note: The "packageIdetifier" will be used to generate subdirectories for these binaries to be installed. + +Using Gitlab.gitlab runner as an example would result in the .exe being placed in "%LOCALAPPDATA%/WinGet_Packages/User/Gitlab.gitlab-runner/" +If a user has configured a path to be used for portable applications that path should be honored. The user should also be able to specify if they want all portable packages placed in the same directory, or in a directory per package. +There will be settings for specifying a default behavior related to whether the path environment variable should or should not be modified. + +A related setting for the uninstall scenario will be able to specify the default behavior for either "--clean" or "--purge". + +### Install + +When the portable application is being installed by the Windows Package manager, an entry will be created in Windows Apps & Features so the user will be able to see the application is installed. + +The "AppPath" subkey will identify the path to the application so the user will be able to execute the program from any path via command prompt. + +The data from “AppsAndFeaturesEntry” in the manifest will be used to specify the name of the package in Windows Apps & Features. Constraints for manifests with portable packages are covered below in the section on validating manifests. If the “AppsAndFeaturesEntry” doesn’t have a “DisplayName” value, then we will use the “PackageName”. +The Product Code will be populated with the "PackageIdentifier" if it is not specified in the “AppsAndFeaturesEntry”. + +No shortcuts or icons will be created for the package. + +>Note: Some portable programs may require dependencies. Dependencies are not covered in this specification and are not yet supported as of the writing of this specification. + +### Upgrade + +The package is upgraded in the same path as the installed version. The first step the Windows Package Manager will perform is an uninstall of the previous version of the package. If the file is in use, the user will be informed the package is running so they can shut it down. Optionally, the user may specify "--force" to forcefully shut the application down for upgrade. + +A new Windows Apps & Features entry is created to correctly report the upgraded version for future potential upgrades. + +There will be no support for installing multiple “side by side” versions of portable packages. + +### Uninstall + +The executable should be removed along with the entry in Apps & Features. The user should also be able to uninstall the package from Apps & Features. + +>Note: the default behavior for uninstalling a portable application with Windows Apps & Features will be to execute uninstall with "--purge" so any files created by the portable application will be removed if they are located in the portable applications directory. + +If the directory is empty after removing the portable application, the directory should also deleted. If the directory is not empty, the user should be informed that other files exist in the directory so it will not be removed. + +### Manifest Validation + +Portable package manifests will only support zero or one "command" value to be specified. In the absence of the "--rename" argument, the value specified in "command" will define the default value for renaming the portable application and subsequently the value specified in the "AppPath" subkey. + +## UI/UX Design + +### Installing a portable package + +```text +winget install Microsoft.NuGet +Found NuGet [Microsoft.NuGet] Version 6.0 +This application is licensed to you by its owner. +Microsoft is not responsible for, nor does it grant any licenses to, third-party packages. +Downloading https://dist.nuget.org/win-x86-commandline/v6.0.0/nuget.exe + ██████████████████████████████ 0.1 MB / 0.1 MB +Successfully verified installer hash +Starting package install... +Successfully installed +``` + +### Upgrading a portable package + +```text +winget upgrade Microsoft.NuGet +Found NuGet [Microsoft.NuGet] Version 7.0 +This application is licensed to you by its owner. +Microsoft is not responsible for, nor does it grant any licenses to, third-party packages. +Downloading https://dist.nuget.org/win-x86-commandline/v7.0.0/nuget.exe + ██████████████████████████████ 0.1 MB / 0.1 MB +Successfully verified installer hash +Starting package install... +Successfully installed +``` + +If the portable application is running when the user performs an upgrade, the user will be informed and given options. + +```text +winget upgrade Microsoft.NuGet +Found NuGet [Microsoft.NuGet] Version 7.0 +This application is licensed to you by its owner. +Microsoft is not responsible for, nor does it grant any licenses to, third-party packages. +Downloading https://dist.nuget.org/win-x86-commandline/v7.0.0/nuget.exe + ██████████████████████████████ 0.1 MB / 0.1 MB +Successfully verified installer hash +Starting package install... +Failed to install NuGet [Microsoft.Nuget]. +Package in use. Either exit the program or use "--force" to upgrade. +``` + +### Uninstalling a portable package + +```text +winget uninstall NuGet +Found NuGet [Microsoft.NuGet] +Starting package uninstall... +Successfully uninstalled +``` + +If the portable application created files in the portable application's directory the user will be informed. + +```text +winget uninstall NuGet +Found NuGet [Microsoft.NuGet] +Starting package uninstall... +The "--purge" argument was not specified. +Files still exist in "%LOCALAPPDATA%/WinGet_Packages/User/Microsoft.NuGet/". +Successfully uninstalled +``` + +## Capabilities + +This will allow users to manage portable applications via the Windows Package Manager. + +### Accessibility + +Any description or output text that is added by consequence of this feature will need to be localized. Moreover, this feature allows a mechanism to add accessibility settings in the future. + +### Security + +This feature will not add any new security risks. All risks associated with this feature have been resolved with the core install, import, upgrade, and uninstall features. + +>Note: We reccommend users leverage the Windows Sandbox when testing manifests on their local machines as the programs may not have been validated from a security perspective prior to being submitted to the Windows Package Manager Community App Repository. + +### Reliability + +This should not introduce any new reliability concerns. + +### Compatibility + +Previous versions of the Windows Package Manager will not cease to function, but they will not be able to apply arguments or settings related to this feature. They will not be able to install portable applications. + +An update to the Windows Package Manager is required to use this feature with the related arguments and settings. + +### Performance, Power, and Efficiency + +This should not introduce any new performande, power, or efficiency concerns in the Windows Package Manager. + +## Potential Issues + +Users may not be aware that there is no support for multiple versions of the same package on their system, so performing an upgrade may not provide they experience they were expecting. + +Users may not be aware that the uninstall behavior by default may leave files on their systems if they were created by a portable application. + +If a user performs uninstall via Windows Apps & Features the default behavior will be to run `winget uninstall package --purge`. + +## Future considerations + +## Resources + +[Portable / Standalone Executables · Discussion #44183 · microsoft/winget-pkgs (github.com)](https://github.com/microsoft/winget-pkgs/discussions/44183) From 83b00e42c5b3b26e81ec9bb9e0b860229e5107da Mon Sep 17 00:00:00 2001 From: denelon Date: Wed, 9 Mar 2022 13:10:09 -0800 Subject: [PATCH 02/14] Update github alias It's not a twitter alias. --- ...82 - Support for installation of portable standalone apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 15261565cb..7fd0699034 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -1,5 +1,5 @@ --- -author: Demitrius Nelon @denelonms +author: Demitrius Nelon @denelon created on: 2022-03-09 last updated: 2022-03-09 issue id: 182 From 505d8077a8d217dfe99fdce94eea570d573dfb55 Mon Sep 17 00:00:00 2001 From: Ryan Fu <69221034+ryfu-msft@users.noreply.github.com> Date: Wed, 9 Mar 2022 14:25:23 -0800 Subject: [PATCH 03/14] Revised edits for portable spec --- ...nstallation of portable standalone apps.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 7fd0699034..191445ed25 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -15,13 +15,13 @@ Several packages do not have an installer. They are simply a binary executable. ## Inspiration -Just because an installer doesn't exist for a particular package, that doesn't mean you shouldn't be able to install it with the Windows Package Manager. +Just because an installer doesn't exist for a particular package doesn't mean you shouldn't be able to install it with the Windows Package Manager. ## Solution Design The installer type “portable” will be added to the enumerated list of installer types to support these types of packages. -When one of these packages is encountered there are several aspects to “installing” these packages and supporting the “upgrade” behavior. Notable concerns include the location of the package, creating or updating an entry in Windows Apps & Features. +When one of these packages is encountered, there are several aspects to “installing” these packages and supporting the “upgrade” behavior. Notable concerns include the location of the package, creating or updating an entry in Windows Apps & Features. ### Command Line Arguments @@ -29,7 +29,7 @@ Users should be able to specify the location for where the program is “install Some packages like GitLab Runner have a file name including extra metadata (gitlab-runner-windows-386.exe). The installation instructions suggest renaming the file after it has been downloaded. In that vein, portable / standalone executables should have their “command” value specified so the Windows Package Manager can perform a default rename behavior. In addition, a “--rename” argument should be added so the user can choose a value they prefer. To have the upgrade scenario honor the custom name, this information should be recorded in the installed packages data store. -Some portable applications generate or consume other files. An additional argument "--purge" will be added for the uninstall scenario to remove all files and subsequently the directory if the user wishes. The corrolary "--preserve" will be used to preserve files if the default setting has been modified. +Some portable applications generate or consume other files. An additional argument "--purge" will be added for the uninstall scenario to remove all files and subsequently the directory if the user wishes. The corollary argument "--preserve" will be used to preserve files if the default setting has been modified. ### Settings @@ -39,19 +39,18 @@ The default path for installing these packages is "%LOCALAPPDATA%/WinGet_Package The corresponding settings are "PortablePackageUserRoot" and "PortablePackageUserRoot". ->Note: The "packageIdetifier" will be used to generate subdirectories for these binaries to be installed. +>Note: The "packageIdentifier" will be used to generate subdirectories for these binaries to be installed to. Using Gitlab.gitlab runner as an example would result in the .exe being placed in "%LOCALAPPDATA%/WinGet_Packages/User/Gitlab.gitlab-runner/" -If a user has configured a path to be used for portable applications that path should be honored. The user should also be able to specify if they want all portable packages placed in the same directory, or in a directory per package. -There will be settings for specifying a default behavior related to whether the path environment variable should or should not be modified. +If a user has configured a path to be used for portable applications, that path should be honored. The user should also be able to specify if they want all portable packages placed in the same directory, or in a directory per package. A related setting for the uninstall scenario will be able to specify the default behavior for either "--clean" or "--purge". ### Install -When the portable application is being installed by the Windows Package manager, an entry will be created in Windows Apps & Features so the user will be able to see the application is installed. +When the portable application is being installed by the Windows Package Manager, an entry will be created in Windows Apps & Features so the user will be able to see that the application is installed. -The "AppPath" subkey will identify the path to the application so the user will be able to execute the program from any path via command prompt. +The "AppPath" registry subkey will identify the path to the application so the user will be able to execute the program from any path via command prompt. The data from “AppsAndFeaturesEntry” in the manifest will be used to specify the name of the package in Windows Apps & Features. Constraints for manifests with portable packages are covered below in the section on validating manifests. If the “AppsAndFeaturesEntry” doesn’t have a “DisplayName” value, then we will use the “PackageName”. The Product Code will be populated with the "PackageIdentifier" if it is not specified in the “AppsAndFeaturesEntry”. @@ -74,7 +73,7 @@ The executable should be removed along with the entry in Apps & Features. The us >Note: the default behavior for uninstalling a portable application with Windows Apps & Features will be to execute uninstall with "--purge" so any files created by the portable application will be removed if they are located in the portable applications directory. -If the directory is empty after removing the portable application, the directory should also deleted. If the directory is not empty, the user should be informed that other files exist in the directory so it will not be removed. +If the directory is empty after removing the portable application, the directory should also be deleted. If the directory is not empty, the user should be informed that other files exist in the directory so it will not be removed. ### Manifest Validation @@ -134,7 +133,7 @@ Starting package uninstall... Successfully uninstalled ``` -If the portable application created files in the portable application's directory the user will be informed. +If the portable application created files in the portable application's directory, the user will be informed. ```text winget uninstall NuGet @@ -157,7 +156,7 @@ Any description or output text that is added by consequence of this feature will This feature will not add any new security risks. All risks associated with this feature have been resolved with the core install, import, upgrade, and uninstall features. ->Note: We reccommend users leverage the Windows Sandbox when testing manifests on their local machines as the programs may not have been validated from a security perspective prior to being submitted to the Windows Package Manager Community App Repository. +>Note: We recommend users leverage the Windows Sandbox when testing manifests on their local machines as the programs may not have been validated from a security perspective prior to being submitted to the Windows Package Manager Community App Repository. ### Reliability @@ -171,7 +170,7 @@ An update to the Windows Package Manager is required to use this feature with th ### Performance, Power, and Efficiency -This should not introduce any new performande, power, or efficiency concerns in the Windows Package Manager. +This should not introduce any new performance, power, or efficiency concerns in the Windows Package Manager. ## Potential Issues @@ -186,3 +185,6 @@ If a user performs uninstall via Windows Apps & Features the default behavior wi ## Resources [Portable / Standalone Executables · Discussion #44183 · microsoft/winget-pkgs (github.com)](https://github.com/microsoft/winget-pkgs/discussions/44183) + +[Application Registration - Win32 Apps](https://docs.microsoft.com/en-us/windows/win32/shell/app-registration) + From e271408e1f2dcc47290a1b3c9398ed65097ced9a Mon Sep 17 00:00:00 2001 From: denelon Date: Wed, 9 Mar 2022 15:13:49 -0800 Subject: [PATCH 04/14] spelling --- .github/actions/spelling/expect.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index e34f3bc6de..a17aeefa59 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -139,6 +139,7 @@ gcpi GES GESMBH GHS +gitlab gity Globals Google From 9fb14482e7777cc3ae4ceeeb3b752e4ef1b00d2e Mon Sep 17 00:00:00 2001 From: denelon Date: Thu, 10 Mar 2022 08:40:56 -0800 Subject: [PATCH 05/14] Icons and Shortcuts --- ...82 - Support for installation of portable standalone apps.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 191445ed25..41c8a4fc18 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -182,6 +182,8 @@ If a user performs uninstall via Windows Apps & Features the default behavior wi ## Future considerations +Some portable applications have icons. The options for creating shortcuts with icons could be considered in the future. + ## Resources [Portable / Standalone Executables · Discussion #44183 · microsoft/winget-pkgs (github.com)](https://github.com/microsoft/winget-pkgs/discussions/44183) From 5d8c4664c63bc5cdbff101829458244756d73559 Mon Sep 17 00:00:00 2001 From: denelon Date: Thu, 10 Mar 2022 08:42:17 -0800 Subject: [PATCH 06/14] Channels --- ...82 - Support for installation of portable standalone apps.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 41c8a4fc18..1604e8be05 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -184,6 +184,8 @@ If a user performs uninstall via Windows Apps & Features the default behavior wi Some portable applications have icons. The options for creating shortcuts with icons could be considered in the future. +Support for channels has not yet been implemented. Some portable applications may have "beta" and "stable" releases. Users may want to have support for both in the future. + ## Resources [Portable / Standalone Executables · Discussion #44183 · microsoft/winget-pkgs (github.com)](https://github.com/microsoft/winget-pkgs/discussions/44183) From 3a6f8e3e30487ca0dff7f2b53d707eebe9df83fd Mon Sep 17 00:00:00 2001 From: denelon Date: Thu, 10 Mar 2022 08:43:54 -0800 Subject: [PATCH 07/14] No App Installer means no uninstall. --- ...82 - Support for installation of portable standalone apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 1604e8be05..1c055360c9 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -178,7 +178,7 @@ Users may not be aware that there is no support for multiple versions of the sam Users may not be aware that the uninstall behavior by default may leave files on their systems if they were created by a portable application. -If a user performs uninstall via Windows Apps & Features the default behavior will be to run `winget uninstall package --purge`. +If a user performs uninstall via Windows Apps & Features the default behavior will be to run `winget uninstall package --purge`. If a user removes the "App Installer" they would not be able to perform uninstall. ## Future considerations From 54dd79ed8f1a39d4799b84aea71f398c896110ad Mon Sep 17 00:00:00 2001 From: denelon Date: Thu, 10 Mar 2022 08:46:25 -0800 Subject: [PATCH 08/14] rendering path --- ...82 - Support for installation of portable standalone apps.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 1c055360c9..44722217ec 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -180,6 +180,8 @@ Users may not be aware that the uninstall behavior by default may leave files on If a user performs uninstall via Windows Apps & Features the default behavior will be to run `winget uninstall package --purge`. If a user removes the "App Installer" they would not be able to perform uninstall. +Displaying a path may be improved with detecting the shell the Windows Package Manager is being executed in. An [Issue](https://github.com/microsoft/winget-cli/issues/1977) was already raised covering the differences in how CMD and PowerShell render or support file system paths. + ## Future considerations Some portable applications have icons. The options for creating shortcuts with icons could be considered in the future. From c331e523d9e6c33aac345659865831ed2cc47fb0 Mon Sep 17 00:00:00 2001 From: denelon Date: Thu, 10 Mar 2022 09:49:18 -0800 Subject: [PATCH 09/14] Update doc/specs/#182 - Support for installation of portable standalone apps.md Co-authored-by: JohnMcPMS --- ...82 - Support for installation of portable standalone apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 44722217ec..6657d1a047 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -37,7 +37,7 @@ Users should have settings to be able to specify a new default location other th The default path for installing these packages is "%LOCALAPPDATA%/WinGet_Packages/User" for user based installs. The default path for installing these packages is "%LOCALAPPDATA%/WinGet_Packages/Machine"for machine wide installs. -The corresponding settings are "PortablePackageUserRoot" and "PortablePackageUserRoot". +The corresponding settings are "PortablePackageUserRoot" and "PortablePackageMachineRoot". >Note: The "packageIdentifier" will be used to generate subdirectories for these binaries to be installed to. From 40b1cb4e7fa0d23c91e11b8814fa65523bbea01c Mon Sep 17 00:00:00 2001 From: denelon Date: Thu, 10 Mar 2022 09:54:22 -0800 Subject: [PATCH 10/14] Update doc/specs/#182 - Support for installation of portable standalone apps.md --- ...82 - Support for installation of portable standalone apps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 6657d1a047..da8c778b7a 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -109,7 +109,7 @@ Starting package install... Successfully installed ``` -If the portable application is running when the user performs an upgrade, the user will be informed and given options. +If the portable application is running when the user performs an upgrade, the user will be informed. ```text winget upgrade Microsoft.NuGet From 33b8c7768ea51997e329320ef5e2d2770eb36a3f Mon Sep 17 00:00:00 2001 From: Ryan Fu Date: Mon, 14 Mar 2022 15:25:26 -0700 Subject: [PATCH 11/14] Update spec with additional clarity --- ...nstallation of portable standalone apps.md | 31 ++++++++++++++----- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index da8c778b7a..856a4ada24 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -27,7 +27,9 @@ When one of these packages is encountered, there are several aspects to “insta Users should be able to specify the location for where the program is “installed” on their machine with the “--location” argument. -Some packages like GitLab Runner have a file name including extra metadata (gitlab-runner-windows-386.exe). The installation instructions suggest renaming the file after it has been downloaded. In that vein, portable / standalone executables should have their “command” value specified so the Windows Package Manager can perform a default rename behavior. In addition, a “--rename” argument should be added so the user can choose a value they prefer. To have the upgrade scenario honor the custom name, this information should be recorded in the installed packages data store. +Some packages like GitLab Runner have a file name including extra metadata (gitlab-runner-windows-386.exe). The installation instructions suggest renaming the file after it has been downloaded. In that vein, a "--rename" argument should be added so the user can choose a value they prefer. To have the upgrade scenario honor the custom name, this information should be recorded in the installed packages data store. + +Portable / standalone executables should have their “command” value specified so the Windows Package Manager can determine the default value to use when creating a new entry in the "App Paths" registry during installation. If no command value is provided, then the entry will use the filename of the exe. Some portable applications generate or consume other files. An additional argument "--purge" will be added for the uninstall scenario to remove all files and subsequently the directory if the user wishes. The corollary argument "--preserve" will be used to preserve files if the default setting has been modified. @@ -35,13 +37,13 @@ Some portable applications generate or consume other files. An additional argume Users should have settings to be able to specify a new default location other than the system default for the Windows Package Manager. -The default path for installing these packages is "%LOCALAPPDATA%/WinGet_Packages/User" for user based installs. The default path for installing these packages is "%LOCALAPPDATA%/WinGet_Packages/Machine"for machine wide installs. +The default path for installing these packages is "%LOCALAPPDATA%/Microsoft/WinGet/Packages/" for user based installs. The default path for installing these packages is "Program Files/Microsoft/WinGet/Packages/"for machine wide x64 installs and "Program Files (x86)/Microsoft/WinGet/Packages/" for machine wide x86 installs. The corresponding settings are "PortablePackageUserRoot" and "PortablePackageMachineRoot". >Note: The "packageIdentifier" will be used to generate subdirectories for these binaries to be installed to. -Using Gitlab.gitlab runner as an example would result in the .exe being placed in "%LOCALAPPDATA%/WinGet_Packages/User/Gitlab.gitlab-runner/" +Using Gitlab.gitlab runner as an example would result in the .exe being placed in "%LOCALAPPDATA%/Microsoft/WinGet/Packages/Gitlab.gitlab-runner/" If a user has configured a path to be used for portable applications, that path should be honored. The user should also be able to specify if they want all portable packages placed in the same directory, or in a directory per package. A related setting for the uninstall scenario will be able to specify the default behavior for either "--clean" or "--purge". @@ -59,9 +61,20 @@ No shortcuts or icons will be created for the package. >Note: Some portable programs may require dependencies. Dependencies are not covered in this specification and are not yet supported as of the writing of this specification. +#### Scope Behavior + +By default, portable apps will be installed with the "User" scope unless specified otherwise by the user through the "--scope" argument or in their settings. This also means that the "scope" field in the manifest will be ignored when installing portable apps. Since portable apps are unique in that they are simply standalone executables that are copied to a specific install location based on scope, it does not seem reasonable to have the manifest enforce an install behavior that is not required. Manifest validation would also need to be updated to show an error to the user that the "scope" field does not apply if a portable installer type is specified. + +#### Installation from multiple sources: + +If the user chooses to install the same package but from a secondary source, the Windows Package Manager will create an additional subdirectory to indicate the source that the package came from. Since entries in the registry must be unique, if the entry in the "App Paths" registry conflicts with an existing entry, then the user will be notified of the conflict and the subkey value will be updated to reflect the change in executable path. In other words, the latest installed package will take precedence. This will require utilizing the installed packages data store to determine whether a package is being installed from two different sources. + + ### Upgrade -The package is upgraded in the same path as the installed version. The first step the Windows Package Manager will perform is an uninstall of the previous version of the package. If the file is in use, the user will be informed the package is running so they can shut it down. Optionally, the user may specify "--force" to forcefully shut the application down for upgrade. +The package is upgraded in the same path as the installed version. The first step the Windows Package Manager will perform is to download the executable to a temporary location, and attempt to copy the exe to the specified install location. If an exe with the same name already exists, the Windows Package Manager will attempt to overwrite the file. If that process fails because the file is currently in use, the user will be informed the package is running so they can shut it down. Optionally, the user may specify "--force" to forcefully shut the application down for upgrade. Once the exe has successfully been copied to the specified install location, the App Paths registry and the entry in Apps & Features will be updated accordingly. + +If the "UninstallPrevious" field is specified in the manifest, then the Windows Package Manager will perform an uninstall of the previous version of the package prior to installing the newer version. A new Windows Apps & Features entry is created to correctly report the upgraded version for future potential upgrades. @@ -71,13 +84,17 @@ There will be no support for installing multiple “side by side” versions of The executable should be removed along with the entry in Apps & Features. The user should also be able to uninstall the package from Apps & Features. ->Note: the default behavior for uninstalling a portable application with Windows Apps & Features will be to execute uninstall with "--purge" so any files created by the portable application will be removed if they are located in the portable applications directory. +>Note: The default behavior for uninstalling a portable application with Windows Apps & Features will be to execute uninstall without "--purge" so any files created by the portable application will be remain if they are located in the portable applications directory. An additional argument for "--wait" will be added that will prompt the user to press any key to exit. This is intended to support this scenario so that the user is aware of any remaining files if they choose to uninstall through Windows Apps & Features. -If the directory is empty after removing the portable application, the directory should also be deleted. If the directory is not empty, the user should be informed that other files exist in the directory so it will not be removed. +If the directory is empty after removing the portable application, the directory should also be deleted. If the directory is not empty, the user should be informed that other files exist in the directory so it will not be removed. ### Manifest Validation -Portable package manifests will only support zero or one "command" value to be specified. In the absence of the "--rename" argument, the value specified in "command" will define the default value for renaming the portable application and subsequently the value specified in the "AppPath" subkey. +Portable package manifests will only support zero or one "command" value to be specified. In the absence of the "--rename" argument, the value specified in "command" will define the default value for renaming the entry in the "App Path" subkey for the portable application. + +If a value for "scope" is specified for a portable installer, the user should be shown an error that the "scope" field is not supported for portable installers. + +Only zero or one entry for "Apps & Features" can be specified for a portable installer. ## UI/UX Design From 7a597215926aeada05f5abd870965ffb77c57baa Mon Sep 17 00:00:00 2001 From: Ryan Fu Date: Mon, 14 Mar 2022 16:18:42 -0700 Subject: [PATCH 12/14] update portable --- ... - Support for installation of portable standalone apps.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 856a4ada24..0569b80190 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -37,7 +37,7 @@ Some portable applications generate or consume other files. An additional argume Users should have settings to be able to specify a new default location other than the system default for the Windows Package Manager. -The default path for installing these packages is "%LOCALAPPDATA%/Microsoft/WinGet/Packages/" for user based installs. The default path for installing these packages is "Program Files/Microsoft/WinGet/Packages/"for machine wide x64 installs and "Program Files (x86)/Microsoft/WinGet/Packages/" for machine wide x86 installs. +The default path for installing these packages is "%LOCALAPPDATA%/Microsoft/WinGet/Packages/" for user based installs. The default path for installing these packages is "Program Files/WinGet/Packages/"for machine wide x64 installs and "Program Files (x86)/WinGet/Packages/" for machine wide x86 installs. The corresponding settings are "PortablePackageUserRoot" and "PortablePackageMachineRoot". @@ -72,7 +72,7 @@ If the user chooses to install the same package but from a secondary source, the ### Upgrade -The package is upgraded in the same path as the installed version. The first step the Windows Package Manager will perform is to download the executable to a temporary location, and attempt to copy the exe to the specified install location. If an exe with the same name already exists, the Windows Package Manager will attempt to overwrite the file. If that process fails because the file is currently in use, the user will be informed the package is running so they can shut it down. Optionally, the user may specify "--force" to forcefully shut the application down for upgrade. Once the exe has successfully been copied to the specified install location, the App Paths registry and the entry in Apps & Features will be updated accordingly. +The package is upgraded in the same path as the installed version. The first step the Windows Package Manager will perform is to download the executable to a temporary location, and attempt to copy the exe to the specified install location. If an exe with the same name already exists, the Windows Package Manager will attempt to overwrite the file. If that process fails because the file is currently in use, the user will be informed the package is running so they can shut it down. Optionally, the user may specify "--force" to forcefully shut the application down for upgrade. Once the exe has successfully been copied to the specified install location, the "App Paths" registry and the entry in "Apps & Features" will be updated accordingly. If the "UninstallPrevious" field is specified in the manifest, then the Windows Package Manager will perform an uninstall of the previous version of the package prior to installing the newer version. From 9a225ce50097fa1d490b35bc2b186ceb845246e1 Mon Sep 17 00:00:00 2001 From: Ryan Fu <69221034+ryfu-msft@users.noreply.github.com> Date: Wed, 16 Mar 2022 16:16:50 -0700 Subject: [PATCH 13/14] Clarify multiple source installation --- ...2 - Support for installation of portable standalone apps.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/specs/#182 - Support for installation of portable standalone apps.md b/doc/specs/#182 - Support for installation of portable standalone apps.md index 0569b80190..0aadb38f3c 100644 --- a/doc/specs/#182 - Support for installation of portable standalone apps.md +++ b/doc/specs/#182 - Support for installation of portable standalone apps.md @@ -67,8 +67,9 @@ By default, portable apps will be installed with the "User" scope unless specifi #### Installation from multiple sources: -If the user chooses to install the same package but from a secondary source, the Windows Package Manager will create an additional subdirectory to indicate the source that the package came from. Since entries in the registry must be unique, if the entry in the "App Paths" registry conflicts with an existing entry, then the user will be notified of the conflict and the subkey value will be updated to reflect the change in executable path. In other words, the latest installed package will take precedence. This will require utilizing the installed packages data store to determine whether a package is being installed from two different sources. +If the user chooses to install the same package but from a secondary source, the Windows Package Manager will append the source name to subdirectory. For example, if GitLabRunner is installed a second time but from the msstore, then the full path would be "%LOCALAPPDATA%/Microsoft/WinGet/Packages/Gitlab.GitLabRunner_msstore/". +Since entries in the registry must be unique, if the entry in the "App Paths" registry conflicts with an existing entry, then the user will be notified of the conflict and the subkey value will remain unchanged. By default we will have "first writer wins (FWW)" behavior, but the user can include the --lww argument ("last writer wins") to have the client replace the subkey value to point to the path of the executable last installed from the second source. ### Upgrade From 8e87d62faf4db56498f7ac9725de1419532e5852 Mon Sep 17 00:00:00 2001 From: Ryan Fu <69221034+ryfu-msft@users.noreply.github.com> Date: Wed, 16 Mar 2022 16:17:59 -0700 Subject: [PATCH 14/14] Update spelling for multiple source installation spec --- .github/actions/spelling/expect.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt index a17aeefa59..47bae083be 100644 --- a/.github/actions/spelling/expect.txt +++ b/.github/actions/spelling/expect.txt @@ -134,6 +134,7 @@ FULLMUTEX FULLWIDTH fundraiser fuzzer +FWW fzanollo gcpi GES @@ -217,6 +218,7 @@ LPWSTR LSTATUS LTDA lw +lww lz malware maxvalue