dopus5 README

The project's README from github.com/BlitterStudio/dopus5. As one markdown file: README.md.

Directory Opus 5

A maintained continuation of Directory Opus 5 Magellan II for AmigaOS 3, AmigaOS 4, MorphOS, and AROS, building on the 2012 APL source release with GCC / cross-toolchain support, modern platform fixes, and ongoing module work.

Looking for the original 2012 APL release notes? See README.legacy. The project was historically known as dopus5allamigas; the repository and project name are now just dopus5.

Supported platforms
Downloads
- Installing
Building
Testing
- Filetype files
- MagicWB icon set
Project status
License and trademarks
Credits
Links

Supported platforms

Platform	Architectures	Notes
AmigaOS 3	m68k 68020-60 (default) and plain m68k 68000	Tested on OS 3.1, 3.1.4, 3.2 and 3.9
AmigaOS 4	PPC
MorphOS	PPC
AROS	i386 (ABIv0), x86_64 / aarch64 (ABIv11)	All three architectures have CI debug + release parity

The 68000 OS3 variant ships in its own archive (DOpus5_<rev>_os3-68000.lha) so users on stock 68000-based hardware (A500, A600, A1000, A2000, CDTV) can run DOpus5 without needing the 020+ build. A1200 / A3000 / A4000 owners should use the regular os3 archive, which targets -m68020-60 -mtune=68030.

Downloads

Pre-built binaries for every supported platform are published under Releases. Each tagged release ships one DOpus5_<rev>_<platform>.lha per target.

Installing

Unpack the archive anywhere, for example to RAM:, and double-click Install DOpus5. The script needs the Installer program that comes with each supported system.

New installation: choose the drawer to install into; the script creates a DOpus5 drawer there.
Upgrade: when the DOpus5: assign points to an existing installation, the script offers to upgrade it. Quit Directory Opus first. The program, libraries, modules, commands, manuals, ARexx scripts, images and stored items are replaced; configuration drawers (Buttons, Environment, Settings, Filetypes, Commands, Desktop, Groups, Themes, Sounds, System) only receive files they do not have yet.
Images and icons: the standard set for RTG and other screens with many colours, or the 8 colour MagicWB set (MWB_DOpus 8 by Trevor Morris and Leo Davidson) for 8 and 16 colour screens, with borderless lister toolbar and FTP bank buttons and "Remap icon images" off in new installations. Suggested for AmigaOS 3 without RTG; remembered in ENVARC:DOpus5Icons. An upgrade that changes the set offers to replace Buttons/Toolbar and Buttons/FTP_image (keeping the old ones as .old). The MagicWB files are also in IconSets/MagicWB of the archive, laid out like the archive root.
Start mode: manually, from an Opus5_Startup icon in SYS:WBStartup when Workbench starts, or (AmigaOS 3) instead of Workbench. Workbench replacement makes DOpus5:C/LoadDB resident as LoadWB in S:User-Startup, so the Startup-Sequence is not changed; hold Shift during boot to get Workbench. The installer remembers the choice in ENVARC:DOpus5Startup.
Optional: a ;BEGIN DOpus5 block in S:User-Startup with the DOpus5: assign and Path DOpus5:C ADD (always written for Workbench replacement). Declining it later empties the block.
Load dopus5.library at boot (AmigaOS 3): for the manual and Workbench start modes, the block can also run DOpus5:C/LoadDOpusLib. Opus then shows AppIcons that programs in SYS:WBStartup added before it started; the library stays in memory until the next reboot. Remembered in ENVARC:DOpus5Preload.

Directory Opus assigns DOpus5: to its own drawer when it starts, so copying the DOpus5 drawer by hand also works for a new installation.

Building

The project builds with cross-compilation toolchains. The recommended way is via the prebuilt Docker images used by CI:

Target	Docker image
AmigaOS 3 (m68k)	`sacredbanana/amiga-compiler:m68k-amigaos`
AmigaOS 4 (PPC)	`amigadev/crosstools:ppc-amigaos`
MorphOS (PPC)	`amigadev/crosstools:ppc-morphos`
AROS i386 (ABIv0)	`midwan/aros-compiler:i386-aros`
AROS x86_64 (ABIv11)	`midwan/aros-compiler:x86_64-aros`
AROS aarch64 (ABIv11)	`midwan/aros-compiler:aarch64-aros`

CI pins the tested Amiga images by digest in the build workflow. Use those digest references instead of the mutable tags above to reproduce a CI build.

The OS3 build stays on the GCC 6.5.0b toolchain: the GCC 16.2.0b amigadev/crosstools:m68k-amigaos-gcc10 image ships a binutils build whose linker emits broken library-call stub relocations (the base reference lands in the text hunk instead of the data hunk, crashing at runtime on the first such call). That toolchain is preserved on the toolchain/gcc16-os3 branch until binutils is fixed upstream.

The OS4 and MorphOS images include the SDKs required by the FTP module (AmiSSL and codesets on OS4, codesets on MorphOS).

The AROS aarch64 image uses Clang 18 with the large, non-PIC code model and links through AROS collect-aros; the other AROS images use GCC. The makefiles select the correct compiler, keep Clang objects separate from older GCC objects, and keep project include directories ahead of the AROS SDK headers. make verify-aarch64-aros builds the program and library, checks that both contain the absolute relocation sequences required by the AROS aarch64 loader, and rejects GOT relocations that the loader cannot apply.

Native builds on Amiga / MorphOS / AROS are also possible if you have a working compiler, libc, and the platform SDK installed.

Per-platform make targets

From inside the toolchain environment:

cd source

make os3            # AmigaOS 3 (default: -m68020-60 -mtune=68030)
make os3-68000      # AmigaOS 3, plain 68000 (-m68000)
make os4            # AmigaOS 4 (PPC)
make mos            # MorphOS (PPC)
make i386-aros      # AROS i386 (ABIv0)
make x86_64-aros    # AROS x86_64 (ABIv11)
make aarch64-aros   # AROS aarch64 (ABIv11, Raspberry Pi 3/4/5 64-bit)

By default the build is a debug build. Add debug=no for the optimised release build:

make os3 debug=no

Release archives

Building the .lha archive uses the same makefile:

cd source
make os3 release debug=no

The release archive ends up under releases/ as DOpus5_<rev>_<platform>.lha (or ..._dev_<platform>.lha for the debug variant). It holds the DOpus5 drawer, the Install DOpus5 script and the IconSets/MagicWB drawer. make <platform> release-package packs an existing build without compiling again.

SFTP support

The FTP module supports SFTP via libssh2.

On AmigaOS 3 / AmigaOS 4 / MorphOS SFTP is always built in: the cross-build helper at source/Modules/ftp/third_party/libssh2/ fetches and statically links libssh2 1.11.1 by default.
On AROS i386 / x86_64 SFTP is opt-in (those toolchain images already provide a shared libssh2):
```
cd source
make i386-aros sftp=yes
make x86_64-aros sftp=yes
```
The current aarch64-aros SDK does not ship libssh2, so sftp=yes is not yet available for that target.

xadopus.module

xadopus.module (archive-as-folder support via xadmaster.library) is built by default for every target. The CI Docker images ship the required proto/xadmaster.h headers.

If the headers aren't installed in a local/native build, it fails with fatal error: proto/xadmaster.h: No such file or directory, which is the expected outcome; install xadmaster's developer headers.

Consult source/makefile, source/makefile.common and the per-platform / per-module makefiles for the full list of targets and options.

Testing

The FTP parser / protocol / TLS tests run on a normal Unix-like host:

make -C source/Modules/ftp -f makefile.tests test

If libssh2 development headers are installed, the SFTP backend tests can also be run:

make -C source/Modules/ftp -f makefile.tests test-libssh2

CI runs both of these before kicking off the platform release builds.

The checks for the base archive and the installer script need lha (or 7z) on the path:

python3 archive/tests/test_basedata_default_drawers.py

Filetype files

archive/tools/filetype_tool.py reads the filetype files Directory Opus keeps in DOpus5:Filetypes and DOpus5:Storage/Filetypes:

python3 archive/tools/filetype_tool.py dump  FILE...  # recognition, icon and actions
python3 archive/tools/filetype_tool.py lint  FILE...  # problems to fix before shipping
python3 archive/tools/filetype_tool.py check FILE...  # decode/re-encode round trip

lint reports a file name that differs from the filetype name, damaged or partly ignored data, icon paths and commands that need assigns a stock system lacks, internal commands that neither Opus nor its modules provide (checked against source/, so run it from a checkout), recognition by file name alone, upper-case datatype IDs and drag'n'drop actions that replace the default Copy MOVEWHENSAME with a plain Copy. Use it to review contributed filetypes before adding them to basedata.lha.

MagicWB icon set

archive/tools/magicwb_iconset.py builds IconSets/MagicWB of basedata.lha from MWB_DOpus8c.lha and the standard files in basedata.lha. Run it after changing a default button bank or an icon the set replaces; it needs LHa for UNIX, so run it in one of the build images:

docker run --rm -v "$PWD:/work" -v "$HOME/Downloads:/mwb" \
  sacredbanana/amiga-compiler:m68k-amigaos \
  sh -c 'cd /work && python3 archive/tools/magicwb_iconset.py /mwb/MWB_DOpus8c.lha /tmp/out --update'

The basedata tests fail when the set's banks or environments no longer match the standard ones, or a default bank uses an image the set lacks.

Project status

Active development happens here. See:

ChangeLog — full change history (most recent at the top)
Releases — packaged builds
Issues — open work and bug reports

Contributions are welcome via pull requests. Please open an issue first if you're planning a larger change so we can sync on direction.

License and trademarks

Directory Opus 5 is released under the AROS Public License (APL) version 1.1 — see COPYING.

Optional builds may include or link third-party components. In particular, the FTP module's SFTP support uses libssh2 and zlib; see THIRD_PARTY_NOTICES.md for the relevant license texts.

"Directory Opus" is a registered trademark of GP Software. The APL trademark licence limits use of the mark to Amiga-like platforms (AmigaOS, MorphOS, AROS, and compatibles); use on Windows, macOS, Linux, etc. is not permitted.

The release of Directory Opus 5 under the APL does not affect the commercial status of Directory Opus for Windows. See https://www.gpsoft.com.au for that product.

Credits

Jonathan Potter / GP Software — original Directory Opus 5 / Magellan II (1993-2012)
DOPUS5 Open Source Team — initial post-APL GCC ports and platform work for OS3 / OS4 / MorphOS / AROS (2012-2013)
Dimitris Panokostas (@midwan) — current maintainer (2023-present)
All other contributors listed in AUTHORS and the project's contributor graph

Special thanks to Olaf Schönweiß and the power2people.org contributors who funded the original 2012 open-source release.