Stabilize Python builds and improve CLI tool usability

.gitignore

@@ -1,5 +1,26 @@
-build
-build-*
+# Common build artifacts
+build/
+build-*/
+bin/
+Makefile
+cmake_install.cmake
+CMakeCache.txt
+CMakeFiles/
+CPackConfig.cmake
+CPackSourceConfig.cmake
+CTestTestfile.cmake
+_deps/
+*.so
+*.a
+*.dylib
+*.dll
+*.exe
+*.o
+*.obj
+*.pyc
+__pycache__/
+
+# Editor/Tools
 compile_commands.json
 .exrc
 .clangd
@@ -8,3 +29,6 @@ compile_commands.json
 .*.swp
 .ycm_extra_conf.py
 .DS_Store
+.ipynb_checkpoints/
+.vscode/
+.idea/

CMakeLists.txt

@@ -1,6 +1,16 @@
 cmake_minimum_required (VERSION 3.10)
 project(ggwave VERSION 0.4.3)
 
+# Initialize and update Git submodules
+message(STATUS "Synchronizing submodules...")
+execute_process(COMMAND git submodule update --init --recursive
+                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                RESULT_VARIABLE submodule_result)
+
+if(NOT submodule_result EQUAL 0)
+    message(FATAL_ERROR "Failed to initialize submodules")
+endif()
+
 set(GGWAVE_VERSION_PYTHON 0.4.3)
 
 set(CMAKE_EXPORT_COMPILE_COMMANDS "on")
@@ -16,7 +26,9 @@ if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
     configure_file(${CMAKE_SOURCE_DIR}/README-tmpl.md                        ${CMAKE_SOURCE_DIR}/README.md @ONLY)
     configure_file(${CMAKE_SOURCE_DIR}/bindings/python/setup-tmpl.py         ${CMAKE_SOURCE_DIR}/bindings/python/setup.py @ONLY)
     configure_file(${CMAKE_SOURCE_DIR}/bindings/javascript/package-tmpl.json ${CMAKE_SOURCE_DIR}/bindings/javascript/package.json @ONLY)
-    configure_file(${CMAKE_SOURCE_DIR}/bindings/ios/Makefile-tmpl            ${CMAKE_SOURCE_DIR}/bindings/ios/Makefile @ONLY)
+    if (GGWAVE_SUPPORT_SWIFT)
+        configure_file(${CMAKE_SOURCE_DIR}/bindings/ios/Makefile-tmpl            ${CMAKE_SOURCE_DIR}/bindings/ios/Makefile @ONLY)
+    endif()
 else()
     set(GGWAVE_STANDALONE OFF)
 endif()

README-tmpl.md

@@ -135,48 +135,87 @@ Other projects using **ggwave** or one of its prototypes:
 
 ## Building
 
-### Dependencies for SDL-based examples
+### Prerequisites
 
-    [Ubuntu]
-    $ sudo apt install libsdl2-dev
+To build all tools and bindings, ensure you have the necessary dependencies installed:
 
-    [Mac OS with brew]
-    $ brew install sdl2
+```bash
+# [Ubuntu/Debian]
+sudo apt install cmake make build-essential libsdl2-dev python3-dev python3-pip
+
+# [Python Tools]
+pip install cython cogapp --user
+```
 
-    [MSYS2]
-    $ pacman -S git cmake make mingw-w64-x86_64-dlfcn mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2
+### Standard Build & Install (Linux, Mac, Windows MSYS2)
 
-### Linux, Mac, Windows (MSYS2)
+The recommended way to build and install `ggwave` is using CMake. This will build the core library, CLI tools, and the Python bindings.
 
 ```bash
-# build
+# 1. Clone the repository
 git clone https://github.com/ggerganov/ggwave --recursive
-cd ggwave && mkdir build && cd build
-cmake ..
+cd ggwave
+
+# 2. Configure (Enable Python bindings)
+cmake . -DGGWAVE_SUPPORT_PYTHON=ON
+
+# 3. Build everything
 make
 
-# running
-./bin/ggwave-cli
+# 4. Install to system path
+sudo make install
+```
+
+> [!IMPORTANT]
+> **Permissions Note:** Always run `make` as a normal user first. If you run `sudo make install` before the build is finished, it may attempt to compile the Python bindings as root, which will fail to find your local `cython` installation and may corrupt file permissions in the repository. If this happens, run `sudo chown $USER:$USER -R .` to restore ownership.
+
+This will install the following tools to `/usr/local/bin`:
+- `ggwave-cli`: Interactive or piped command line tool for sending/receiving data.
+- `ggwave-to-file`: Encode text into a WAV file.
+- `ggwave-from-file`: Decode text from a WAV file.
+- `waver`: GUI application for data exchange.
+
+**Example CLI usage:**
+```bash
+# Interactive mode
+ggwave-cli
+
+# One-off transmission via pipe (auto-exits when done)
+echo "All is done" | ggwave-cli
 ```
 
 #### Local Debian packages
 
 Build reproducible `libggwave-dev` and `python3-ggwave` Debian packages:
 ```bash
-# Fetch source
-git clone https://github.com/ggerganov/ggwave --recursive
-cd ggwave
-
-# Configure
 cmake . -DGGWAVE_BUILD_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release
-
-# Build
 make deb
-
-# Install
 sudo dpkg -i dist/*.deb
 ```
 
+### Python
+
+You can install `ggwave` directly from PyPI or build it from source.
+
+#### From PyPI (Standard User / Termux)
+This is the easiest method for consumers. It works out of the box on most platforms:
+```bash
+pip install ggwave
+```
+
+More info: https://pypi.org/project/ggwave/
+
+#### From Source (Developer / Git Repo)
+When building from the Git repository, you must manually sync the core C++ sources and handle build-time dependencies. Use `--no-build-isolation` to ensure your local `cython` and `cogapp` installations are used:
+
+```bash
+cd bindings/python
+make ggwave          # Syncs core C++ headers and source files
+pip install . --user --no-build-isolation
+```
+
+**Note on Cog:** If you have the Replicate `cog` CLI installed, the build system will automatically prefer `python3 -m cogapp` to avoid name collisions.
+
 ### Emscripten
 
 ```bash
@@ -187,14 +226,6 @@ emcmake cmake ..
 make
 ```
 
-### Python
-
-```bash
-pip install ggwave
-```
-
-More info: https://pypi.org/project/ggwave/
-
 ### Node.js
 
 ```bash

README.md

@@ -135,48 +135,87 @@ Other projects using **ggwave** or one of its prototypes:
 
 ## Building
 
-### Dependencies for SDL-based examples
+### Prerequisites
 
-    [Ubuntu]
-    $ sudo apt install libsdl2-dev
+To build all tools and bindings, ensure you have the necessary dependencies installed:
 
-    [Mac OS with brew]
-    $ brew install sdl2
+```bash
+# [Ubuntu/Debian]
+sudo apt install cmake make build-essential libsdl2-dev python3-dev python3-pip
+
+# [Python Tools]
+pip install cython cogapp --user
+```
 
-    [MSYS2]
-    $ pacman -S git cmake make mingw-w64-x86_64-dlfcn mingw-w64-x86_64-gcc mingw-w64-x86_64-SDL2
+### Standard Build & Install (Linux, Mac, Windows MSYS2)
 
-### Linux, Mac, Windows (MSYS2)
+The recommended way to build and install `ggwave` is using CMake. This will build the core library, CLI tools, and the Python bindings.
 
 ```bash
-# build
+# 1. Clone the repository
 git clone https://github.com/ggerganov/ggwave --recursive
-cd ggwave && mkdir build && cd build
-cmake ..
+cd ggwave
+
+# 2. Configure (Enable Python bindings)
+cmake . -DGGWAVE_SUPPORT_PYTHON=ON
+
+# 3. Build everything
 make
 
-# running
-./bin/ggwave-cli
+# 4. Install to system path
+sudo make install
+```
+
+> [!IMPORTANT]
+> **Permissions Note:** Always run `make` as a normal user first. If you run `sudo make install` before the build is finished, it may attempt to compile the Python bindings as root, which will fail to find your local `cython` installation and may corrupt file permissions in the repository. If this happens, run `sudo chown $USER:$USER -R .` to restore ownership.
+
+This will install the following tools to `/usr/local/bin`:
+- `ggwave-cli`: Interactive or piped command line tool for sending/receiving data.
+- `ggwave-to-file`: Encode text into a WAV file.
+- `ggwave-from-file`: Decode text from a WAV file.
+- `waver`: GUI application for data exchange.
+
+**Example CLI usage:**
+```bash
+# Interactive mode
+ggwave-cli
+
+# One-off transmission via pipe (auto-exits when done)
+echo "All is done" | ggwave-cli
 ```
 
 #### Local Debian packages
 
 Build reproducible `libggwave-dev` and `python3-ggwave` Debian packages:
 ```bash
-# Fetch source
-git clone https://github.com/ggerganov/ggwave --recursive
-cd ggwave
-
-# Configure
 cmake . -DGGWAVE_BUILD_EXAMPLES=OFF -DCMAKE_BUILD_TYPE=Release
-
-# Build
 make deb
-
-# Install
 sudo dpkg -i dist/*.deb
 ```
 
+### Python
+
+You can install `ggwave` directly from PyPI or build it from source.
+
+#### From PyPI (Standard User / Termux)
+This is the easiest method for consumers. It works out of the box on most platforms:
+```bash
+pip install ggwave
+```
+
+More info: https://pypi.org/project/ggwave/
+
+#### From Source (Developer / Git Repo)
+When building from the Git repository, you must manually sync the core C++ sources and handle build-time dependencies. Use `--no-build-isolation` to ensure your local `cython` and `cogapp` installations are used:
+
+```bash
+cd bindings/python
+make ggwave          # Syncs core C++ headers and source files
+pip install . --user --no-build-isolation
+```
+
+**Note on Cog:** If you have the Replicate `cog` CLI installed, the build system will automatically prefer `python3 -m cogapp` to avoid name collisions.
+
 ### Emscripten
 
 ```bash
@@ -187,14 +226,6 @@ emcmake cmake ..
 make
 ```
 
-### Python
-
-```bash
-pip install ggwave
-```
-
-More info: https://pypi.org/project/ggwave/
-
 ### Node.js
 
 ```bash

bindings/python/Makefile

@@ -11,9 +11,9 @@ DEB_BUILD_DIR := $(DEST)$(PKG_NAME)-$(VERSION)
 DEB_VER := 0
 DEB := python3-$(PKG_NAME)_$(VERSION)-$(DEB_VER)_$(ARCH).deb
 SOURCE_DATE_EPOCH := $(shell git log -1 --pretty=%ct)
-SOURCE_PKG_CMD := python -m build --sdist
+SOURCE_PKG_CMD := python3 -m build --sdist
 DEB_BUILD_CMD := dpkg-buildpackage -rfakeroot -uc -us
-COGAPP ?= $(shell which cog || which cogapp)
+COGAPP ?= $(shell python3 -m cogapp --help > /dev/null 2>&1 && echo "python3 -m cogapp" || which cogapp || which cog)
 
 .PHONY:
 ggwave: