diff --git a/README.md b/README.md index a9d694f..fb76662 100644 --- a/README.md +++ b/README.md @@ -5,231 +5,79 @@ SPDX-License-Identifier: GPL-3.0-or-later # Host-Tools -A collection of AmigaOS tools designed to bridge the gap between the Amiberry emulator and the host operating system (Linux, macOS, and Windows; see Requirements for per-tool host support). +A classic AmigaOS 68k package for [Amiberry](https://github.com/BlitterStudio/amiberry). It includes 11 command-line tools for working with the host operating system, two AHI audio drivers, and an MHI MP3 decoder library. The guest tools run inside Amiberry; host integrations target Linux, macOS, or Windows as noted below. -These tools allow you to execute commands, open files, launch interactive shells, inspect host paths, and use common host desktop integrations directly from the Amiga environment. +## What's included -## The Tools +| Component | What it does | Installed location | +| --- | --- | --- | +| 11 command tools | Run host commands, open files and URLs, use the host shell, paths, desktop, clipboard, downloads, and environment | `C:` | +| UAE AHI driver | Classic UAE 16-bit stereo AHI output | `DEVS:AHI/uae.audio`, `DEVS:AudioModes/UAE` | +| UAESND AHI driver | AHI output through Amiberry's UAESND sound board | `DEVS:AHI/uaesnd.audio`, `DEVS:AudioModes/UAESND` | +| UAE MHI MP3 decoder | Offloads MP3 decoding to Amiberry | `LIBS:MHI/mhiuae.library` | +| AmigaGuide | On-Amiga reference for the tools and drivers | `HELP:/Host-Tools.guide` | -### 1. host-run -**Execute host commands securely.** -`host-run` allows you to execute any command on the host system. It is designed to be robust and secure: -- **Safe Quoting**: Arguments are automatically safeguarded, allowing you to pass complex filenames and parameters (including spaces and special characters) without issues. -- **Path Translation**: Amiga paths (e.g., `Work:Documents/file.txt`) are automatically resolved to their host counterparts before execution. +The installer lets you select these components separately. The audio drivers and MHI library are not command-line tools; installing them does not change your audio preferences. -**Usage:** -```shell -host-run [arguments...] -``` - -### 2. host-multiview -**Open files or URLs with the default host application.** -Think of this as an "Open with..." command for the Amiga. It sends a file or URL to the host system, which then opens it using the default associated application (e.g., VLC for videos, Preview for images, your browser for URLs). -- **Cross-Platform**: Works natively on **Linux** (via `xdg-open`) and **macOS** (via `open`). -- **Seamless**: Perfect for integration with DefIcons to open media files or documents on the host. - -**Usage:** -```shell -host-multiview [filename2|URL2 ...] -``` - -### 3. host-shell -**Interactive Host Terminal.** -Opens a fully interactive terminal session on the host system, right inside your Amiga CLI. -- **Interactive**: Supports `vi`, `htop`, and other interactive TUI applications. -- **Shell Support**: Starts your host user's login shell (Bash, Zsh, Fish, etc.) so profile files can set paths and environment variables. -- **Raw Mode**: Provides a true terminal experience. -- **Terminal Size**: The host terminal is sized to match the Amiga console window, so full-screen programs render correctly. - -**Usage:** -```shell -host-shell [command] -``` - -### 4. host-path -**Print translated host paths.** -`host-path` resolves existing Amiga paths and prints their host-side paths. It is useful for debugging mounted directories and scripts. - -**Usage:** -```shell -host-path [path2 ...] -``` - -### 5. host-reveal -**Reveal files in the host file manager.** -`host-reveal` selects the file in Finder on macOS, in Explorer on Windows, or in the default Linux file manager through the `FileManager1` D-Bus interface (GNOME Files, Dolphin, Nemo, and others). When no compatible file manager is available, it opens the containing directory instead. - -**Usage:** -```shell -host-reveal [path2 ...] -``` - -### 6. host-notify -**Send host desktop notifications.** -`host-notify` uses `notify-send` on Linux or `osascript` on macOS when available. It is not yet available on Windows hosts. - -**Usage:** -```shell -host-notify -host-notify <message...> -``` - -### 7. host-edit -**Open files in the host desktop editor.** -`host-edit` uses `open -t` on macOS and the host's default GUI text editor on Linux via `xdg-mime` and `gtk-launch`, with `xdg-open`, `VISUAL`, or `EDITOR` as fallbacks. - -**Usage:** -```shell -host-edit <path> [path2 ...] -``` - -### 8. host-clip -**Use the host clipboard.** -`host-clip` copies text to the host clipboard or prints the current host clipboard contents. Without text arguments, `host-clip copy` reads standard input verbatim, so multi-line text and command output can be piped or redirected to the host clipboard. Paste also preserves trailing line breaks. Text is converted between the Amiga's ISO-8859-1 character set and the host's encoding: through `iconv` on Linux and macOS, and inherently through PowerShell's Unicode pipeline on Windows. - -**Usage:** -```shell -host-clip [copy] <text...> -host-clip copy < file -host-clip paste -``` - -### 9. host-info -**Print host integration details.** -`host-info` reports basic host OS, shell, editor, opener, and clipboard backend details. - -**Usage:** -```shell -host-info -``` - -### 10. host-download -**Download files through the host.** -`host-download` fetches an HTTP, HTTPS, FTP, or FTPS URL with the host's `curl` (or `wget`) and saves it to any Amiga path — `RAM:`, hardfiles, and directory mounts all work, because the file is written by the tool through AmigaDOS. The host handles HTTPS/TLS, giving classic AmigaOS access to modern servers. -- **Live Progress**: With a current Amiberry, the file streams to the Amiga as it downloads, with a percentage display when the server reports a size. -- **Transactional**: Data is written to a temporary file beside the destination. Failed, stalled, or aborted downloads (Ctrl-C) never leave a partial result, and `FORCE` preserves the previous file until the replacement is complete. -- **Flexible Destination**: With no destination the file is saved in the current directory under its URL name; a directory destination keeps the URL name. - -**Usage:** -```shell -host-download <URL> [<destination>] [FORCE] -``` - -### 11. host-env -**Get and set host user environment variables.** -`host-env` reads, writes, removes, and lists environment variables on the host. On Windows it updates the user's persistent environment. On Linux and macOS it writes persistent values to `$HOME/.host-tools-env`; source that file from your host shell startup files if you want future host login shells to import those values automatically. -- **Persistent**: Changes are intended for future host processes. -- **Private by Default**: On Linux and macOS, the managed file is written atomically with mode `0600`. Values must fit on one line. -- **Scoped Safely**: Existing host shells, desktop apps, and Amiberry's parent process cannot have their live environment changed by a child process. - -**Usage:** -```shell -host-env get NAME -host-env set NAME VALUE -host-env unset NAME -host-env list -``` - ---- +For detailed usage, see the [command reference](https://github.com/BlitterStudio/host-tools/wiki/Command-Tools), [audio and MP3 guide](https://github.com/BlitterStudio/host-tools/wiki/Audio-and-MP3), and [getting started guide](https://github.com/BlitterStudio/host-tools/wiki/Getting-Started) in the wiki. The package also includes an offline AmigaGuide. Wiki pages are authored in [`docs/wiki/`](docs/wiki/) alongside the code and published to the GitHub wiki. ## Requirements -- **Amiberry v6.0+** (or a version with updated `uaelib` support). -- "Native Code" execution must be enabled in Amiberry settings. -- All tools work on **Linux and macOS hosts**. Current Windows support is summarized below. +- **Amiberry v6.0+** (or a build with the required `uae.resource`/`uaelib` support); enable **Native Code** execution in Amiberry settings for the command tools and MHI library. UAESND AHI also needs the UAESND sound board enabled. +- The command tools run on **Linux and macOS hosts** except where the Windows support table below adds support. Audio components use Amiberry's emulated interfaces; the table describes command tools only. | Tool | Linux | macOS | Windows | | --- | :---: | :---: | :---: | | `host-run`, `host-multiview`, `host-shell`, `host-edit`, `host-notify` | Yes | Yes | — | | `host-path`, `host-reveal`, `host-clip`, `host-info`, `host-download`, `host-env` | Yes | Yes | Yes | -Windows integrations require a current Amiberry. PowerShell and Explorer handle desktop operations, and `curl.exe` ships with Windows 10 and later. - -- For status-aware tools (`host-reveal`, `host-notify`, `host-clip`, `host-info`, and `host-env`), a newer Amiberry build with the `HostShell_Status` trap reports host command failures immediately. Press Ctrl-C to cancel a stuck host command. An idle command times out after approximately 30 seconds on status-aware builds or 5 seconds on older builds. -- Linux desktop integration uses `xdg-utils` (`xdg-open`, `xdg-mime`) and GTK's `gtk-launch` when available. Notifications use `notify-send`; clipboard support uses `wl-clipboard`, `xclip`, or `xsel`; file selection in `host-reveal` uses `gdbus` when present. Character set conversion uses `iconv` when present. -- `host-download` uses the host's `curl` or `wget` (`curl.exe` on Windows) and accepts HTTP, HTTPS, FTP, and FTPS URLs. Live streaming progress requires an Amiberry build with pipe-based HostShell sessions; on older Linux and macOS builds the tool falls back to a two-phase transfer that downloads on the host first. - ## Exit Codes All tools follow AmigaDOS conventions: `0` on success, `10` (`RETURN_ERROR`) when an operation fails or the tool is invoked with missing or invalid arguments, and `2` when `uae.resource` is unavailable (for example, when running outside Amiberry or with Native Code execution disabled). The explicit `?` help request returns `0`. ## Installation -1. Download the latest release from the [Releases Page](../../releases). -2. Extract the `Host-Tools-<version>.lha` archive. -3. Open the `Host-Tools` drawer and run `Install`. - -The installer shows a component checklist for the command tools, AmigaGuide documentation, the UAE and UAESND AHI audio drivers, and the UAE MHI MP3 decoder library. Before replacing an existing versioned file, it shows the installed and package versions and asks whether to replace or skip it. Files without version strings are still checked for existence and ask before overwrite. It does not edit startup files, system settings, AHI preferences, or existing driver configuration. - -For manual installation, copy the binaries (`host-run`, `host-multiview`, `host-shell`, `host-path`, `host-reveal`, `host-notify`, `host-edit`, `host-clip`, `host-info`, `host-download`, `host-env`) from the package `C` drawer to `C:` or anywhere in your system path. To install the UAE AHI driver manually, copy `Devs/AHI/uae.audio` to `DEVS:AHI/` and `Devs/AudioModes/UAE` to `DEVS:AudioModes/`. To install the UAESND AHI driver manually, copy `Devs/AHI/uaesnd.audio` to `DEVS:AHI/` and `Devs/AudioModes/UAESND` to `DEVS:AudioModes/`. To install the UAE MHI MP3 decoder manually, copy `Libs/MHI/mhiuae.library` to `LIBS:MHI/`. The UAESND driver plays each AHI channel through a hardware audio stream and requires the UAESND sound board to be enabled in the Amiberry configuration. The MHI library is independent of the selected AHI output mode and forwards MP3 decoding to Amiberry through `uae.resource`. +1. Download the latest archive and optional `.lha.sha256` checksum from the [Releases page](../../releases). +2. Extract `Host-Tools-<version>.lha`. +3. Open the `Host-Tools` drawer and run `Install`. -## Examples - -### Web Browsing -Open a URL in the host's default browser (works on both Linux and macOS): -```shell -host-multiview https://github.com/BlitterStudio/amiberry -``` -Or using `host-run` with the platform-specific command: -```shell -host-run xdg-open https://github.com/BlitterStudio/amiberry -``` +All five components are selected by default. **Novice** installs everything; **Intermediate** lets you select components and copies files automatically; **Expert** lets you select components and asks before replacing existing files (showing installed and package versions where available). The installer does not edit startup files, system settings, AHI preferences, or driver configuration. The guide goes to `HELP:<language>/`, using `English` if no language is set. -### Playing Media -Play a video file located on an Amiga partition using the host's media player: -```shell -host-run vlc "Work:Videos/My Holiday.mp4" -``` -Or simply: -```shell -host-multiview "Work:Videos/My Holiday.mp4" -``` +For manual installation: -### Downloading Files -Download an archive from Aminet straight to the RAM disk, with the host handling HTTPS: -```shell -host-download https://aminet.net/dev/misc/example.lha RAM: -``` +| Component | Copy from the package | Copy to | +| --- | --- | --- | +| Command tools | Contents of `C/` | `C:` or another directory on your command path | +| UAE AHI | `Devs/AHI/uae.audio`, `Devs/AudioModes/UAE` | `DEVS:AHI/`, `DEVS:AudioModes/` respectively | +| UAESND AHI | `Devs/AHI/uaesnd.audio`, `Devs/AudioModes/UAESND` | `DEVS:AHI/`, `DEVS:AudioModes/` respectively | +| UAE MHI | `Libs/MHI/mhiuae.library` | `LIBS:MHI/` | +| AmigaGuide | `Help/Host-Tools.guide` | `HELP:<language>/` | -### DefIcons Integration -Make AmigaOS automatically open `.mkv` files on the host: -1. Open **DefIcons**. -2. Add/Edit the `mkv` entry. -3. Set the **Default Tool** to `host-multiview`. -4. Now, double-clicking any MKV file in Workbench will play it on the host! +Choose an AHI mode in AHI preferences after installing a driver; installing both drivers does not select one for you. ## Building -This project is built using **GitHub Actions**. Every push to `master` or a version tag triggers a build using the `sacredbanana/amiga-compiler:m68k-amigaos` Docker image. +GitHub Actions builds and tests on pushes to `master`, version tags, and pull requests to `master`, using `sacredbanana/amiga-compiler:m68k-amigaos`. Tag builds also publish the release archive and its SHA-256 checksum. -To build locally (requires the m68k-amigaos cross-compiler): +With the m68k-amigaos cross-compiler, `vasmm68k_mot`, and `lha` installed locally: ```shell make all +make test +make package ``` -To build locally with the same Docker image used by CI: -```shell -docker run --rm -v "$PWD":/work -w /work sacredbanana/amiga-compiler:m68k-amigaos make all -``` - -To run only the native command-builder tests: -```shell -make test-unit -``` - -To run the complete test suite, including a fresh cross-build and package verification, use the CI image: +Alternatively, build and test with the AmigaOS 3 cross-toolchain container: ```shell -docker run --rm -v "$PWD":/work -w /work sacredbanana/amiga-compiler:m68k-amigaos make clean test +docker run --rm -v "$PWD":/work -w /work amigadev/crosstools:m68k-amigaos-gcc10 make all +docker run --rm -v "$PWD":/work -w /work amigadev/crosstools:m68k-amigaos-gcc10 make test +docker run --rm -v "$PWD":/work -w /work amigadev/crosstools:m68k-amigaos-gcc10 make package ``` -To build a release archive: -```shell -make package -``` +On Windows, keep `tests/*.sh` and `CHANGELOG.md` checked out with LF line endings. CRLF scripts fail in `/bin/sh`, and CRLF changelog lines fail the package's release-link check. -The package target creates and verifies `Host-Tools-<version>.lha`, containing a structured `Host-Tools` drawer with the Installer script, command tools, README, license, changelog, AmigaGuide documentation, the UAE and UAESND AHI driver files, and the UAE MHI MP3 decoder library. +Use `make test-unit` for native command tests without a cross-build; `make test` also runs packaging and source checks. -Native package builds also require `lha`. The Docker build image contains this tool. +The `package` target verifies the staged `Host-Tools` drawer before producing `Host-Tools-<version>.lha`. The archive contains the installer, all five components listed above, the README, license, and changelog. Release metadata is defined once in [`version.mk`](version.mk). See [`docs/RELEASING.md`](docs/RELEASING.md) for the release checklist and [`CHANGELOG.md`](CHANGELOG.md) for user-visible changes. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index a8f4861..380b667 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -18,9 +18,12 @@ exact version; CI rejects a mismatch before building. ```shell docker run --rm -v "$PWD":/work -w /work \ - sacredbanana/amiga-compiler:m68k-amigaos make clean test package + amigadev/crosstools:m68k-amigaos-gcc10 make clean test package ``` + On Windows, check out `tests/*.sh` and `CHANGELOG.md` with LF line endings; + CRLF breaks the shell tests and the changelog link check inside Docker. + 5. Confirm that `git status --short` contains only intentional source changes. `make package` already verifies the package layout and all release version strings before writing the archive. @@ -42,3 +45,23 @@ exact version; CI rejects a mismatch before building. The tag workflow rebuilds and verifies the package, publishes the `.lha` and `.lha.sha256` artifacts, and creates the GitHub release with generated notes. + +## Publishing the wiki + +The detailed wiki pages are authored in `docs/wiki/`, not in the wiki editor. +Publish them when their content changes, after the corresponding repository +change is merged; keep the release archive's README and AmigaGuide usable +offline. The GitHub wiki is a separate Git repository, so merging this +repository does not update the live wiki: + +```shell +gh repo clone BlitterStudio/host-tools.wiki ../host-tools.wiki +cp docs/wiki/*.md ../host-tools.wiki/ +git -C ../host-tools.wiki add Home.md Getting-Started.md Command-Tools.md Audio-and-MP3.md +git -C ../host-tools.wiki commit -m "Update Host-Tools user guides" +git -C ../host-tools.wiki push +``` + +Clone only once; for subsequent updates, pull the wiki's latest commit before +copying the pages. The first page of a new wiki must be created in GitHub's +wiki editor before its Git repository can be cloned. diff --git a/docs/wiki/Audio-and-MP3.md b/docs/wiki/Audio-and-MP3.md new file mode 100644 index 0000000..ae37452 --- /dev/null +++ b/docs/wiki/Audio-and-MP3.md @@ -0,0 +1,38 @@ +<!-- +SPDX-FileCopyrightText: 2020-2026 Dimitris Panokostas +SPDX-License-Identifier: GPL-3.0-or-later +--> + +# Audio drivers and MP3 decoding + +Host-Tools includes two separate AHI drivers and an MHI MP3 decoder library for classic AmigaOS 68k under Amiberry. The installer selects all three by default but lets you install any combination. It copies files only: **you must choose an AHI mode in AHI preferences** yourself. The MHI decoder does not need an AHI mode of its own. + +| Component | Package files | Installed location | +| --- | --- | --- | +| UAE AHI | `Devs/AHI/uae.audio`, `Devs/AudioModes/UAE` | `DEVS:AHI/`, `DEVS:AudioModes/` | +| UAESND AHI | `Devs/AHI/uaesnd.audio`, `Devs/AudioModes/UAESND` | `DEVS:AHI/`, `DEVS:AudioModes/` | +| UAE MHI MP3 | `Libs/MHI/mhiuae.library` | `LIBS:MHI/` | + +## UAE AHI driver + +The `UAE :16 bit HIFI Stereo++` AHI mode outputs 16-bit stereo audio with panning through Amiberry's classic UAE AHI v1 host interface. Install both `uae.audio` and its `UAE` AudioMode file, then select that mode in AHI preferences to use it. Installation alone does not switch the active AHI output. + +## UAESND AHI driver + +Enable the **UAESND sound board** in Amiberry before selecting a `uaesnd` mode in AHI preferences. This driver sends each AHI channel to a hardware audio stream, avoiding Amiga-side mixing. It provides: + +| Mode shown in AHI | Output | +| --- | --- | +| `uaesnd: Stereo` | 16-bit stereo | +| `uaesnd: HiFi Stereo` | 32-bit stereo | +| `uaesnd: 7.1` | 32-bit multichannel | + +Install both `uaesnd.audio` and its `UAESND` AudioMode file. The installer neither enables the sound board nor changes your AHI preferences. + +## UAE MHI MP3 decoder + +`mhiuae.library` implements the classic MHI decoder interface for MHI-compatible MP3 players. It passes MP3 buffers through `uae.resource`; Amiberry uses its host mpg123 decoder and feeds the resulting audio into the emulator's audio mixer. MP3 decoding therefore does not consume Amiga CPU time. + +Install the library in `LIBS:MHI/`. It does not configure AHI and can be used with Paula, UAE AHI, UAESND AHI, or another chosen AHI driver. Enable **Native Code** execution in Amiberry for the `uae.resource` integration. + +Return to [Getting started](Getting-Started) for the installer and host requirements, or to [Command tools](Command-Tools) for the other programs in the package. diff --git a/docs/wiki/Command-Tools.md b/docs/wiki/Command-Tools.md new file mode 100644 index 0000000..6ff7400 --- /dev/null +++ b/docs/wiki/Command-Tools.md @@ -0,0 +1,139 @@ +<!-- +SPDX-FileCopyrightText: 2020-2026 Dimitris Panokostas +SPDX-License-Identifier: GPL-3.0-or-later +--> + +# Command tools + +Run these commands in an AmigaOS CLI under Amiberry with **Native Code** enabled. The package installer copies all 11 to `C:` when the command-tools component is selected. Enter `?` after a command for its built-in usage help. Existing Amiga paths are translated to host paths where a tool accepts file arguments; a host application cannot normally open a file that exists only inside an unmapped hardfile. + +| Host support | Tools | +| --- | --- | +| Linux, macOS, Windows (current Amiberry) | `host-path`, `host-reveal`, `host-clip`, `host-info`, `host-download`, `host-env` | +| Linux and macOS | `host-run`, `host-multiview`, `host-shell`, `host-edit`, `host-notify` | + +## host-run + +```text +host-run <command> [arguments...] +``` + +Runs a command on a Linux or macOS host. Existing Amiga file arguments (such as `Work:Videos/clip.mp4`) are resolved to host paths. Arguments are quoted for the host shell, but the command must be installed on the host; `host-run` does not install software or make files inside an unmapped Amiga volume visible to host applications. + +```text +host-run vlc "Work:Videos/My Holiday.mp4" +``` + +For the host's default file or URL handler, use `host-multiview` instead of choosing a platform-specific command. + +## host-multiview + +```text +host-multiview <filename|URL> [filename2|URL2 ...] +``` + +Opens each file or URL with the Linux or macOS host's default application. An existing Amiga path is translated before it is handed to the host. A URL is passed through as a URL. + +```text +host-multiview https://github.com/BlitterStudio/amiberry +host-multiview "Work:Videos/My Holiday.mp4" +``` + +You can also set it as a DefIcons default tool for file types you want to open on the host. + +## host-shell + +```text +host-shell [command] +``` + +Opens an interactive Linux or macOS login shell inside the Amiga CLI, or runs the supplied command in that login shell. Host shell startup files can supply its environment. Full-screen terminal programs work in the Amiga console; the host terminal's size is taken from the Amiga window when `host-shell` starts. Restart it after resizing the window. + +## host-path + +```text +host-path <path> [path2 ...] +``` + +Prints the translated host-side path of each **existing** Amiga path. Use it to check whether a mounted directory is accessible to host applications before passing that path to `host-run`, `host-edit`, or `host-multiview`. + +## host-reveal + +```text +host-reveal <path> [path2 ...] +``` + +Shows translated files in the host file manager: Finder selects them on macOS, Explorer selects them on Windows, and Linux file managers supporting the FileManager1 D-Bus interface select them. On Linux without a compatible file manager, the containing directory is opened instead. + +## host-notify + +```text +host-notify <message> +host-notify <title> <message...> +``` + +Sends a desktop notification using `notify-send` on Linux or `osascript` on macOS. The one-argument form uses the message as the notification text; the second form supplies a title and message. Windows is not supported. + +## host-edit + +```text +host-edit <path> [path2 ...] +``` + +Opens files in the Linux or macOS host's desktop text editor. macOS uses `open -t`; on Linux the tool looks for a default GUI text editor through `xdg-mime` and `gtk-launch`, then falls back to `xdg-open`, `VISUAL`, or `EDITOR` where available. + +## host-clip + +```text +host-clip [copy] <text...> +host-clip copy < file +host-clip paste +``` + +Copies arguments to the host clipboard, reads standard input when `copy` has no text argument, or prints the clipboard contents with `paste`. Input and output preserve line breaks, including trailing newlines. Text converts between the Amiga's ISO-8859-1 encoding and the host's encoding via `iconv` on Linux/macOS or PowerShell on Windows. POSIX hosts use an available `wl-clipboard`, `xclip`, or `xsel` backend. + +```text +host-clip copy "Hello from Amiga" +host-clip paste +``` + +## host-info + +```text +host-info +``` + +Prints the detected host operating system and the available shell, opener, editor, and clipboard backend. Run this before troubleshooting a missing desktop integration. + +## host-download + +```text +host-download <URL> [<destination>] [FORCE] +``` + +Downloads an HTTP, HTTPS, FTP, or FTPS URL through the host's `curl` or `wget` (`curl.exe` on Windows), then writes the result through AmigaDOS. This works with `RAM:`, hardfiles, and directory mounts, including destinations the host cannot see directly. + +Without a destination, the URL filename is used in the current directory. An existing directory destination also keeps the URL filename. An existing file is not overwritten unless `FORCE` is specified. The tool writes to a temporary file beside the destination and moves it into place after a successful transfer; failed or cancelled transfers do not replace the old file. Ctrl-C aborts a download. A current Amiberry can stream data with live progress; older Linux/macOS builds first download to the host and then transfer to the Amiga. + +```text +host-download https://github.com/BlitterStudio/host-tools/releases/download/v2.6/Host-Tools-2.6.lha RAM: +``` + +## host-env + +```text +host-env get NAME +host-env set NAME VALUE +host-env unset NAME +host-env list +``` + +Reads, sets, removes, or lists **host user** environment variables. Names use ASCII letters, digits, and underscores and cannot start with a digit. Values cannot contain line breaks. + +On Windows, values are stored in the persistent user environment. On Linux/macOS, changes are written atomically to `$HOME/.host-tools-env` with mode `0600`; source that file from your host shell startup files to import values into later login shells. Neither approach changes the environment of host processes that are already running, including Amiberry's parent process. + +## Exit codes and host requirements + +Commands return `0` on success, `10` for missing/invalid arguments or failed operations, and `2` if `uae.resource` is unavailable (for example, outside Amiberry or with Native Code disabled). The `?` help request returns `0` when `uae.resource` is available. + +Linux desktop commands depend on the corresponding host utilities (`xdg-utils`, `notify-send`, clipboard backends, and optionally `gdbus` or `iconv`). Downloads require `curl` or `wget` on POSIX hosts and `curl.exe` on Windows. Status-aware host commands can be cancelled with Ctrl-C; idle operations time out after about 30 seconds with newer Amiberry `HostShell_Status` support or 5 seconds without it. See [Getting started](Getting-Started) for installation and host support. diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md new file mode 100644 index 0000000..fd8613a --- /dev/null +++ b/docs/wiki/Getting-Started.md @@ -0,0 +1,59 @@ +<!-- +SPDX-FileCopyrightText: 2020-2026 Dimitris Panokostas +SPDX-License-Identifier: GPL-3.0-or-later +--> + +# Getting started + +## Requirements + +Run the classic AmigaOS 68k tools in Amiberry v6.0+ or a build with the required `uae.resource`/`uaelib` support. Enable **Native Code** execution for the command tools and MHI decoder. To use the UAESND AHI driver, also enable the **UAESND sound board** in Amiberry. The two AHI drivers are guest audio components; the host support table below describes the **command tools**, not the audio drivers. + +| Host | Supported commands | +| --- | --- | +| Linux and macOS | All 11 commands | +| Windows (current Amiberry) | `host-path`, `host-reveal`, `host-clip`, `host-info`, `host-download`, `host-env` | + +Linux desktop integration uses `xdg-utils`, `notify-send`, and, depending on the operation, `gtk-launch`, `gdbus`, `iconv`, or a clipboard backend (`wl-clipboard`, `xclip`, `xsel`). Downloads use host `curl` or `wget`; on Windows they use `curl.exe` (included in Windows 10 and later). Windows desktop integrations use PowerShell and Explorer. Check the [command reference](Command-Tools) for individual requirements and exit codes. + +## Install from a release + +1. Download the latest `Host-Tools-<version>.lha` from the [releases page](https://github.com/BlitterStudio/host-tools/releases); a `.lha.sha256` checksum is published beside it. +2. Extract the archive and open the `Host-Tools` drawer. +3. Run `Install`. All five components are selected by default: command tools, AmigaGuide, UAE AHI, UAESND AHI, and UAE MHI MP3. + +**Novice** installs everything and replaces existing files. **Intermediate** lets you select components and copies files automatically. **Expert** lets you select components and asks before replacing files, showing installed and package versions when available. The installer does not change startup scripts, system settings, AHI preferences, or existing driver configuration. It installs the guide to `HELP:<language>/Host-Tools.guide`, using `English` if no language is set. + +For manual installation, copy the command programs from the archive's `C/` drawer to `C:` or another directory on the Amiga command path. Copy each audio component's files to the locations in [Audio and MP3](Audio-and-MP3). The AmigaGuide can be copied to `HELP:<language>/`. + +## Try the host commands + +These are Amiga CLI examples. Files must already exist where the example expects them; host applications can use Amiga paths backed by host-visible mounts. + +Open a URL in the Linux or macOS host browser: + +```text +host-multiview https://github.com/BlitterStudio/amiberry +``` + +Open a video on a host-visible Amiga volume using the host's default application (Linux/macOS): + +```text +host-multiview "Work:Videos/My Holiday.mp4" +``` + +To use a particular host application instead, run it explicitly (Linux/macOS, with the application installed on the host): + +```text +host-run vlc "Work:Videos/My Holiday.mp4" +``` + +Download an archive onto the Amiga RAM disk on any supported host: + +```text +host-download https://github.com/BlitterStudio/host-tools/releases/download/v2.6/Host-Tools-2.6.lha RAM: +``` + +To open a class of files on the host from Workbench, set its **DefIcons** default tool to `host-multiview` (Linux/macOS). `host-path Work:Videos` prints the host path for a mounted directory when you need to check where it resolves. + +For usage and behavior of the remaining commands, see [Command tools](Command-Tools). For choosing and installing audio modes, see [Audio and MP3](Audio-and-MP3). diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..d748f6f --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,14 @@ +<!-- +SPDX-FileCopyrightText: 2020-2026 Dimitris Panokostas +SPDX-License-Identifier: GPL-3.0-or-later +--> + +# Host-Tools + +Host-Tools is a classic AmigaOS 68k package for [Amiberry](https://github.com/BlitterStudio/amiberry). It provides 11 commands that connect the Amiga to its Linux, macOS, or Windows host, two AHI audio drivers, and an MHI MP3 decoder. + +- [Getting started](Getting-Started): requirements, host support, installation, and examples. +- [Command tools](Command-Tools): syntax and host behavior for all 11 commands. +- [Audio and MP3](Audio-and-MP3): AHI modes, the UAESND sound board, and MHI decoding. + +For an offline reference, install the `Host-Tools.guide` AmigaGuide from the release archive. The [README](https://github.com/BlitterStudio/host-tools#readme) has the package summary and build instructions. These wiki pages are published from `docs/wiki/` in the source repository; edit that versioned source alongside implementation changes rather than editing the published copy separately. diff --git a/drivers/mhi/src/mhiuae.h b/drivers/mhi/src/mhiuae.h index 1390ac7..d4a72db 100644 --- a/drivers/mhi/src/mhiuae.h +++ b/drivers/mhi/src/mhiuae.h @@ -10,6 +10,7 @@ #include <exec/semaphores.h> #include <exec/tasks.h> #include <exec/types.h> +#include <dos/dos.h> #include "mhi_abi.h" diff --git a/package/Help/Host-Tools.guide b/package/Help/Host-Tools.guide index 7ef18f2..c57a313 100644 --- a/package/Help/Host-Tools.guide +++ b/package/Help/Host-Tools.guide @@ -4,9 +4,9 @@ @wordwrap @node Main "Host-Tools" -Host-Tools provides command line utilities for classic AmigaOS 68k systems running under Amiberry. +Host-Tools is a classic AmigaOS 68k package for Amiberry. It includes 11 command-line tools for host integration, two optional AHI audio drivers, an MHI MP3 decoder, and this guide. The command tools run inside the Amiga; their host support varies by tool. -Installed components: +Choose a topic: @{"Command tools" link Commands} @{"UAE AHI audio driver" link AHI} @@ -17,7 +17,7 @@ Installed components: @endnode @node Commands "Command Tools" -The command tools are installed to C: when selected in the installer. +Select "Command tools" in the installer to copy all 11 programs to C:. Linux and macOS support all 11; six also work on Windows with a current Amiberry (see Installation Notes). Each command accepts ? for usage help. @{"host-run" link HostRun} executes host commands. @{"host-multiview" link HostMultiView} opens files or URLs with the host default application. @@ -34,7 +34,7 @@ The command tools are installed to C: when selected in the installer. @endnode @node AHI "UAE AHI Audio Driver" -The UAE AHI audio driver is installed only when selected in the installer. +Select "UAE AHI audio driver" in the installer to copy the driver and its AudioMode. Installed files: @@ -50,7 +50,7 @@ The installer does not change AHI preferences. Select the UAE mode in AHI prefer @endnode @node UAESND "UAESND AHI Audio Driver" -The UAESND AHI audio driver is installed only when selected in the installer. +Select "UAESND AHI audio driver" in the installer to copy the driver and its AudioMode. Installed files: @@ -70,7 +70,7 @@ The installer does not change AHI preferences. Select a uaesnd mode in AHI prefe @endnode @node MHI "UAE MHI MP3 Decoder" -The UAE MHI MP3 decoder library is installed only when selected in the installer. +Select "UAE MHI MP3 decoder" in the installer to copy the library. Installed file: @@ -216,13 +216,13 @@ Variable names must use ASCII letters, digits, and underscores, and must not sta @endnode @node InstallNotes "Installation Notes" -The installer copies selected files only. It shows a component checklist first. When a versioned file already exists, Installer shows the installed and package versions and asks whether to replace or skip it. Files without version strings are still checked for existence and ask before overwrite. +The installer offers five components: command tools, this AmigaGuide, UAE AHI, UAESND AHI, and the UAE MHI MP3 decoder. All are selected by default. Novice installs everything; Intermediate lets you select components and copies files automatically; Expert lets you select components and asks before replacing files, showing installed and package versions when available. -It does not edit startup files, system settings, or existing driver configuration. +The guide is installed to HELP:<language>/Host-Tools.guide (English if no language is set). The drivers go to DEVS:AHI/ and DEVS:AudioModes/; the decoder goes to LIBS:MHI/. The installer does not edit startup files, system settings, AHI preferences, or driver configuration. -Native Code execution must be enabled in Amiberry for these tools to communicate with the host. +Enable Native Code execution in Amiberry to use the command tools and MHI decoder. Enable the UAESND sound board in Amiberry before using the UAESND AHI modes. Choose your preferred AHI mode in AHI preferences yourself. -All tools work on Linux and macOS hosts. On Windows hosts, host-path, host-download, host-clip, host-reveal, host-info, and host-env are supported with a current Amiberry; the remaining tools require a Linux or macOS host. +All command tools work on Linux and macOS hosts. On Windows hosts, host-path, host-download, host-clip, host-reveal, host-info, and host-env are supported with a current Amiberry; the remaining command tools require a Linux or macOS host. Host commands used by host-reveal, host-notify, host-clip, host-info, and host-env can be cancelled with Ctrl-C. Idle commands time out after approximately 30 seconds on status-aware Amiberry builds or 5 seconds on older builds.