From 5020c97296fbeef509979a42dcfcd6e382eff3d8 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 10 Jun 2025 13:21:44 +0000 Subject: [PATCH] I've added detailed build from source instructions to README. This commit updates the README.md file to include a new 'Building from Source' section. This section provides step-by-step instructions for compiling Picocrypt on Linux, macOS, and Windows, including prerequisites, dependency management, and platform-specific build commands. For macOS and Windows, optional instructions are also included for creating application bundles/installers and embedding resources to match the official release builds more closely. --- MACOS_BUILD_INSTRUCTIONS.md | 123 ++++++++++++++++++++++++++++++++ README.md | 137 +++++++++++++++++++++++++++++++++++- 2 files changed, 259 insertions(+), 1 deletion(-) create mode 100644 MACOS_BUILD_INSTRUCTIONS.md diff --git a/MACOS_BUILD_INSTRUCTIONS.md b/MACOS_BUILD_INSTRUCTIONS.md new file mode 100644 index 0000000..565de01 --- /dev/null +++ b/MACOS_BUILD_INSTRUCTIONS.md @@ -0,0 +1,123 @@ +# Building Picocrypt on macOS + +This guide provides instructions on how to build Picocrypt from source on a macOS system. + +## Prerequisites + +1. **Xcode Command Line Tools:** + If you haven't already, install the Xcode Command Line Tools. Open Terminal and run: + ```bash + xcode-select --install + ``` + Follow the on-screen prompts. + +2. **Homebrew:** + Homebrew is a package manager for macOS. If you don't have it, install it by following the instructions at [brew.sh](https://brew.sh/). + +3. **Go Programming Language:** + * **Installation:** It's recommended to install the latest stable version of Go. You can download it from the [official Go website](https://golang.org/dl/) or install it via Homebrew: + ```bash + brew install go + ``` + * **Environment Setup (if not using Homebrew's Go):** Ensure your `GOPATH` and `GOROOT` environment variables are set up correctly, and that `$GOPATH/bin` and `$GOROOT/bin` are in your `PATH`. If you installed Go via Homebrew, this is usually handled automatically. You can check your Go environment with `go env`. + +4. **Git:** + If not already installed (usually comes with Xcode Command Line Tools), install Git: + ```bash + brew install git + ``` + +5. **Required Libraries (GLFW & GLEW):** + Picocrypt's GUI depends on GLFW and GLEW. Install them using Homebrew: + ```bash + brew install glfw glew + ``` + +## Build Steps + +1. **Clone the Repository:** + Open Terminal and navigate to the directory where you want to store the Picocrypt source code. Then clone the repository: + ```bash + git clone https://github.com/Picocrypt/Picocrypt.git + cd Picocrypt + ``` + +2. **Navigate to the Source Directory:** + The main Go source code is located in the `src` directory. + ```bash + cd src + ``` + +3. **Download Dependencies:** + Picocrypt uses Go modules to manage its dependencies. Download them using: + ```bash + go mod download + ``` + This command inspects the `go.mod` file and downloads all necessary libraries. + +4. **Compile the Application:** + Build the Picocrypt application. The `-ldflags="-s -w"` flags help reduce the binary size by stripping debug symbols. `CGO_ENABLED=1` is necessary as Picocrypt uses Cgo for its GUI components. + ```bash + CGO_ENABLED=1 go build -v -ldflags="-s -w" -o Picocrypt Picocrypt.go + ``` + The `-v` flag enables verbose output, showing the packages as they are compiled. The `-o Picocrypt` flag specifies the output file name. + + Upon successful compilation, you will find an executable file named `Picocrypt` in the `src` directory. + +## Packaging (Optional - Creating a .app Bundle and .dmg) + +The following steps replicate the process used in the GitHub Actions workflow to create a standard macOS application bundle (`.app`) and a disk image (`.dmg`). + +1. **Prepare the .app Bundle Structure:** + The Picocrypt repository includes a template for the `.app` bundle. + * Go back to the root directory of the cloned repository: + ```bash + cd .. + ``` + * The template `Picocrypt.app.zip` is usually located in `dist/macos/`. For a manual build, you might need to ensure this path is correct or download/copy this template if it's not present directly. Assuming it's in `dist/macos/`: + ```bash + cp dist/macos/Picocrypt.app.zip . + unzip -d Picocrypt.app Picocrypt.app.zip + rm Picocrypt.app.zip + ``` + This creates a `Picocrypt.app` directory with the necessary bundle structure. + +2. **Move the Compiled Binary:** + Move the `Picocrypt` executable you compiled in the `src` directory into the `.app` bundle: + ```bash + mv src/Picocrypt Picocrypt.app/Contents/MacOS/Picocrypt + ``` + +3. **Create the .dmg Disk Image:** + * Create a temporary directory to hold the `.app` bundle for DMG creation: + ```bash + mkdir out + cp -R Picocrypt.app out/ + ``` + * Use `hdiutil` to create the DMG: + ```bash + hdiutil create Picocrypt.dmg -volname Picocrypt -fs APFS -format UDZO -srcfolder out + ``` + This will create `Picocrypt.dmg` in the root of the repository. + + * Clean up the temporary directory: + ```bash + rm -rf out + rm -rf Picocrypt.app + ``` + +You should now have a `Picocrypt.dmg` file ready for distribution or installation. The standalone `Picocrypt` executable (from `src/Picocrypt`) can also be run directly if you don't need the `.app` bundle. + +## Running Picocrypt + +* **Directly:** You can run the compiled binary from the `src` directory: + ```bash + ./src/Picocrypt + ``` +* **From .app Bundle:** If you created the `.app` bundle, you can run it by double-clicking `Picocrypt.app` in Finder, or from Terminal: + ```bash + open Picocrypt.app + ``` +* **From .dmg:** Open `Picocrypt.dmg`, and then drag `Picocrypt.app` to your Applications folder. Run it from there. + +This completes the build process for Picocrypt on macOS. diff --git a/README.md b/README.md index 74292ab..5b5c08c 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

Picocrypt

-Picocrypt is a very small (hence Pico), very simple, yet very secure encryption tool that you can use to protect your files. It's designed to be the go-to tool for encryption, with a focus on security, simplicity, and reliability. Picocrypt uses the secure XChaCha20 cipher and the Argon2id key derivation function to provide a high level of security, even from three-letter agencies like the NSA. Your privacy and security is under attack. Take it back with confidence by protecting your files with Picocrypt. +Picocrypt is a very small (hence Pico), very simple, yet very secure encryption tool that you can use to protect your files. It'sdesigned to be the go-to tool for encryption, with a focus on security, simplicity, and reliability. Picocrypt uses the secure XChaCha20 cipher and the Argon2id key derivation function to provide a high level of security, even from three-letter agencies like the NSA. Your privacy and security is under attack. Take it back with confidence by protecting your files with Picocrypt.

Picocrypt

@@ -45,6 +45,141 @@ A functionally limited web app is available PicoGo is a community-developed port of Picocrypt to platforms like Android and iOS using the Fyne GUI library. Feel free to try it out, but keep in mind that it is *not* part of the official core Picocrypt project (like the platforms listed above) and thus not subject to the same scrutiny and standards that the core project is. So, **use it with caution and diligence** during its experimental phase. +# Building from Source + +This section provides guidance on how to build Picocrypt from source on various operating systems. The build process requires Go version 1.24 or newer. + +### Linux + +1. **Install Prerequisites:** + You'll need Go and several C libraries for the GUI components. + ```bash + sudo apt update + sudo apt install -y golang-go gcc xorg-dev libgtk-3-dev libgl1-mesa-dev libglu1-mesa + ``` + *(Note: Ensure the `golang-go` package from your distribution provides Go >=1.24. If not, install Go manually from [go.dev/dl](https://go.dev/dl/))* + +2. **Clone the Repository:** + ```bash + git clone https://github.com/Picocrypt/Picocrypt.git + cd Picocrypt + ``` + +3. **Download Go Dependencies:** + Navigate to the source directory and download the module dependencies. + ```bash + cd src + go mod download + ``` + +4. **Build Picocrypt:** + Compile the application. `CGO_ENABLED=1` is required. + ```bash + CGO_ENABLED=1 go build -v -ldflags="-s -w" -o Picocrypt Picocrypt.go + ``` + The `Picocrypt` executable will be created in the `src` directory. You can move it to a directory in your system's `$PATH` (e.g., `~/.local/bin` or `/usr/local/bin`) for easier access. + +### macOS + +1. **Install Prerequisites:** + * **Xcode Command Line Tools:** If not already installed, open Terminal and run: + ```bash + xcode-select --install + ``` + * **Homebrew:** Install from [brew.sh](https://brew.sh/) if you don't have it. + * **Go:** Install Go (>=1.24) via Homebrew or from [go.dev/dl](https://go.dev/dl/): + ```bash + brew install go + ``` + * **Git:** + ```bash + brew install git + ``` + * **Required Libraries (GLFW & GLEW):** + ```bash + brew install glfw glew + ``` + +2. **Clone the Repository:** + ```bash + git clone https://github.com/Picocrypt/Picocrypt.git + cd Picocrypt + ``` + +3. **Download Go Dependencies:** + ```bash + cd src + go mod download + ``` + +4. **Build Picocrypt:** + ```bash + CGO_ENABLED=1 go build -v -ldflags="-s -w" -o Picocrypt Picocrypt.go + ``` + The `Picocrypt` executable will be in the `src` directory. + +5. **(Optional) Create .app Bundle and .dmg:** + To create a standard macOS application bundle and disk image: + * Navigate to the repository root: `cd ..` + * Copy and unzip the app template (ensure `dist/macos/Picocrypt.app.zip` exists): + ```bash + cp dist/macos/Picocrypt.app.zip . + unzip -d Picocrypt.app Picocrypt.app.zip + rm Picocrypt.app.zip + ``` + * Move the compiled binary into the bundle: + ```bash + mv src/Picocrypt Picocrypt.app/Contents/MacOS/Picocrypt + ``` + * Create the DMG: + ```bash + mkdir TempDMGFolder + cp -R Picocrypt.app TempDMGFolder/ + hdiutil create Picocrypt.dmg -volname Picocrypt -fs APFS -format UDZO -srcfolder TempDMGFolder + rm -rf TempDMGFolder Picocrypt.app + ``` + +### Windows + +1. **Install Prerequisites:** + * **Go:** Install Go (>=1.24) from [go.dev/dl](https://go.dev/dl/). + * **C Compiler (for CGO):** MSYS2 with MinGW-w64 is recommended. + * Install MSYS2 from [www.msys2.org](https://www.msys2.org/). + * From an MSYS2 MINGW64 shell, install GCC: + ```bash + pacman -Syu + pacman -S mingw-w64-x86_64-gcc + ``` + * Ensure the MinGW-w64 `bin` directory (e.g., `C:\msys64\mingw64in`) is in your system `PATH`. + * **Git:** Install Git from [git-scm.com/download/win](https://git-scm.com/download/win). + +2. **Clone the Repository:** + Use Git Bash or Command Prompt with Git: + ```bash + git clone https://github.com/Picocrypt/Picocrypt.git + cd Picocrypt + ``` + +3. **Download Go Dependencies:** + ```bash + cd src + go mod download + ``` + +4. **Build Picocrypt (Basic Executable):** + In Command Prompt or PowerShell (ensure GCC is in PATH): + ```cmd + set CGO_ENABLED=1 + go build -v -ldflags="-s -w -H=windowsgui" -o Picocrypt.exe Picocrypt.go + ``` + This creates `Picocrypt.exe` in the `src` directory. This version lacks the embedded icon and manifest. + +5. **(Optional) Embedding Resources and Compressing:** + To replicate the official release builds, you'll need: + * **Resource Hacker:** Download from its official website (e.g., angusj.com/resourcehacker). + * **UPX:** Download from [upx.github.io](https://upx.github.io/). + The GitHub Actions workflow file `.github/workflows/build-windows.yml` contains specific command-line examples for using Resource Hacker to embed the icon (`images/key.ico`), manifest (`dist/windows/manifest.xml`), and version information (`dist/windows/versioninfo.rc`), and then UPX for compression. These steps are complex and require careful execution. Always download these tools from their official sources. + # Why Picocrypt? Why should you use Picocrypt instead of VeraCrypt, 7-Zip, BitLocker, or Cryptomator? Here are a few reasons why you should choose Picocrypt: