From 525474bfbdafca5993d37f58018ff7d17c9c279f Mon Sep 17 00:00:00 2001 From: Baipyrus Date: Wed, 20 Nov 2024 11:34:47 +0100 Subject: [PATCH] Updated README in regards to #6 and in general terms --- README.md | 150 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 84 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 312524d..0196684 100644 --- a/README.md +++ b/README.md @@ -10,35 +10,40 @@ access to settings and toggling proxies. ## Features - Switch internet proxy settings for various applications and the system. -- Manage configurations through a `configs.json` file. -- Command-line interface with commands like `set`, `unset`, and `save`. -- System tray icon with options to enable and disable proxies, open settings, -save configurations, or exit the application. +- Configuration files stored in `configs/` for better organization and flexibility. +- CLI commands (`set`, `unset`, `save`, `debug`) for managing proxy settings. +- System tray icon for fast access to all functionality. ## Installation -You should download the [latest release](https://github.com/Baipyrus/ProxySwitcher/releases) -archive, **extract all contents** to a dedicated directory and then simply execute -the [`.\install.ps1`](./install.ps1) script within a Windows Powershell. +This project offers two installation methods: via PowerShell or manually. In the +end, you will always be using the [`.\install.ps1`](./install.ps1) script which will +automatically download the Project if necessary and adds it to `%PATH%`. All contents +will then be installed to `%LOCALAPPDATA%/Programs` for a user installation. -Alternatively, you could simply run the following command in a Windows PowerShell: +### PowerShell Installation + +Run the following command in Windows PowerShell: ```powershell -# Using 'Invoke-RestMethod' and 'Invoke-Expression' irm 'https://raw.githubusercontent.com/Baipyrus/ProxySwitcher/main/install.ps1' | iex ``` +### Manual Installation + +1. Download the [latest release](https://github.com/Baipyrus/ProxySwitcher/releases). +2. Extract the archive to somewhere accessible to your user. +3. Run the [`.\install.ps1`](./install.ps1) script within a Windows Powershell instance. + ## Usage -Generally, the [Installation](#installation) step will install both the program, -its assets, and a shortcut for the Windows Startmenu for your current userprofile. -Additionally, the program will also be added to the user's `%PATH%` Variable and -will this be executable from within the command-line. However, you will either need -to navigate into the program directory (`C:\Users\[Username]\AppData\Local\Programs\ProxySwitcher\`) +First, you will either need to navigate into the program directory (`C:\Users\[Username]\AppData\Local\Programs\ProxySwitcher\`) manually or specify a path to any directory containing configuration files using the flag `-c, --configs string configurations path (default "configs/")`. To keep it simple, it is still recommended to use the program in system tray or -directly via code. This latter option will be explained next: +directly via code. + +In case you want to run the code directly: - Clone the repository: @@ -51,83 +56,87 @@ directly via code. This latter option will be explained next: - **set**: Enable all saved proxies including system proxy. ```powersell - # .\ProxySwitcher.exe set + # ProxySwitcher.exe set go run . set ``` - **unset**: Disable all saved proxies including system proxy. ```powersell - # .\ProxySwitcher.exe unset + # ProxySwitcher.exe unset go run . unset ``` - **save**: Saves a new configuration to set a proxy for. ```powersell - # .\ProxySwitcher.exe save + # ProxySwitcher.exe save go run . save ``` - **debug**: Prints all proxy configurations after generating corresponding commands. ```powersell - # .\ProxySwitcher.exe debug + # ProxySwitcher.exe debug go run . save ``` ### Configuration -The programs for which the proxy settings should be managed are stored in [`configs/`](https://github.com/Baipyrus/ProxySwitcher/tree/main/configs), -wherein you can then create a JSON file per command group. These files can easily -be modified directly or generated through the `save` command. For examples, -please take a look at the [default config](https://github.com/Baipyrus/ProxySwitcher/tree/main/configs) -or at the following block: +Proxy configurations are organized within the [`configs/`](https://github.com/Baipyrus/ProxySwitcher/tree/main/configs), +directory, with each JSON file representing a configuration for a specific command +group. You can modify or add your own configurations in any JSON file in this directory +directly, or you could use the `save` command in a CLI to save settings for you. +For examples configurations, please take a look at the [default config](https://github.com/Baipyrus/ProxySwitcher/tree/main/configs). -```js -[ - { - "name": "test1", // Default CMD Name - "cmd": "echo 'Hello, World!'", // Optional - "set": [ - { - "args": [ - "http" - ], // Optionally empty - "type": "text" // Default; Optional - "equator": " " // Default; Optional - }, // Writes "echo 'Hello, World!' http ", followed - // by your system proxy, to a powershell process. - { - "args": [ - "https" - ], // Optionally empty - "equator": "=" // Optional - } // Writes "echo 'Hello, World!' https=", followed - // by your system proxy, to a powershell process. - ], // Optional - "unset": [] - // "unset" has the contents as "set" above - // and it is also optional. - }, { - "name": "test2", // Default CMD Name - "cmd": "echo '$PRSW_ARG $PRSW_ARG'", // Optional - "set": [ - { - "args": [ - "https" - ], // Optionally empty - "type": "variable" // Optional - } // Writes "echo 'https '" - // to a powershell process. - ] // Optional - } -] +#### Structure + +Any of these JSON files are used to build commands that the program can run to `set` +and `unset` the proxy configuration of other programs. The system proxy will be set +automatically upon calling the respective commands. The actual proxy address and +port will be automatically detected from your system settings, if available. + +Once in one of these JSON files, you will need to create an object (`{}`) with the +following properties: + +```javascript +{ + // Either "name" or "cmd" or both is required: + "name": "npm", + // Use a custom '$PRSW_ARG' variable to inject + // arguments into "cmd" at given positions: + // "cmd": "npm", + + "set": [ + { + "args": [ + "config", + "set", + "proxy" + ], + // Optionally specify a separator between the + // last argument and the injected proxy string: + "equator": "=", // Default: " " + // Optionally specify a surrounding character + // for injected proxy string: + "surround": "\"", + // Optionally specify the type of command. If + // using '$PRSW_ARG' in "cmd", set to "variable". + "type": "variable", // Default: "text" + // Optionally choose to skip injecting the + // proxy string for pre-config commands. + "discard": "true" // Default: "false" + } + ], + + // Use the same structure as "set": + "unset" [] +} ``` ### System Tray Icon -Right-click the system tray icon to: +The system tray icon provides a context menu for all commands: - **Properties**: View and modify system proxy settings. - **Enable Proxy**: Enable all saved proxies including system proxy. @@ -138,8 +147,17 @@ Right-click the system tray icon to: ## Building 1. Clone the repository as seen above in [Usage](#usage) -2. Run the following command: +2. If running on Windows Subsystem for Linux: + - Set environment variables to build for windows: + + ```bash + GOOS=windows + GOARCH=amd64 + ``` + +3. Run the following command: ```powershell - GOOS=windows GOARCH=amd64 go build -o build/ -v ./... + # Remove-Item -Recurse -Force -ErrorAction SilentlyContinue build/ + go build -o build/ -v ./... ```