fz0x1/Picocrypt
1
0
Fork 0
mirror of https://github.com/Picocrypt/Picocrypt.git synced 2025-06-27 13:46:13 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

I've added detailed build from source instructions to README.

Browse source 
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.
This commit is contained in:
google-labs-jules[bot] 2025-06-10 13:21:44 +00:00
parent 8647c8a42e
commit 5020c97296
2 changed files with 259 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

123
MACOS_BUILD_INSTRUCTIONS.md Normal file
View file

@ -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.

137
README.md
View file

@ -5,7 +5,7 @@
<p align="center"><img align="center" src="/images/logo.svg" width="512" alt="Picocrypt"></p>
Picocrypt is a very small (hence <i>Pico</i>), very simple, yet very secure encryption tool that you can use to protect your files. It's designed to be the <i>go-to</i> 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. <strong>Your privacy and security is under attack. Take it back with confidence by protecting your files with Picocrypt.</strong>
Picocrypt is a very small (hence <i>Pico</i>), very simple, yet very secure encryption tool that you can use to protect your files. It'sdesigned to be the <i>go-to</i> 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. <strong>Your privacy and security is under attack. Take it back with confidence by protecting your files with Picocrypt.</strong>
<br>
<p align="center"><img align="center" src="/images/screenshot.png" width="318" alt="Picocrypt"></p>
@ -45,6 +45,141 @@ A functionally limited web app is available <a href="https://picocrypt.github.io
## Mobile 🚧
An experimental project <a href="https://github.com/Picocrypt/PicoGo">PicoGo</a> 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:
<ul>