{"id":21196283,"url":"https://github.com/neildavis/amiga_asmdev_workflow","last_synced_at":"2025-07-10T05:30:34.259Z","repository":{"id":252125647,"uuid":"839495971","full_name":"neildavis/amiga_asmdev_workflow","owner":"neildavis","description":"A Linux workflow and example application for automated build of Amiga programs in 68K assembly","archived":false,"fork":false,"pushed_at":"2024-11-27T12:43:05.000Z","size":787,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-05T10:51:10.286Z","etag":null,"topics":["68k","68k-assembly","adf","amiga","amiga-development","asm","asm68k","bare-metal","bare-metal-programming","cross-platform","linux","vasm","vlink","workflow","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"Assembly","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neildavis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-07T18:16:52.000Z","updated_at":"2025-02-02T15:22:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"3942fd81-409d-419d-b27a-0ddd4111811b","html_url":"https://github.com/neildavis/amiga_asmdev_workflow","commit_stats":null,"previous_names":["neildavis/amiga_asmdev_workflow"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/neildavis/amiga_asmdev_workflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neildavis%2Famiga_asmdev_workflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neildavis%2Famiga_asmdev_workflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neildavis%2Famiga_asmdev_workflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neildavis%2Famiga_asmdev_workflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neildavis","download_url":"https://codeload.github.com/neildavis/amiga_asmdev_workflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neildavis%2Famiga_asmdev_workflow/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264535988,"owners_count":23624404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["68k","68k-assembly","adf","amiga","amiga-development","asm","asm68k","bare-metal","bare-metal-programming","cross-platform","linux","vasm","vlink","workflow","workflow-automation"],"created_at":"2024-11-20T19:35:17.668Z","updated_at":"2025-07-10T05:30:34.253Z","avatar_url":"https://github.com/neildavis.png","language":"Assembly","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Amiga ASM Development Workflow #\n\n## Introduction ##\n\nThis repository provides and demonstrates an automation workflow for certain aspects\nof development in 68K assembly for the Commodore Amiga series of computers.\nIt has been developed for use in a Linux environment using 'freely available' tools.\n[FOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) tools are used\nas much as possible, but some components (e.g. `vasm` and `vlink`) are distributed\nunder [their own licenses](./tools/LICENSE.md).\n\nThe following features are provided and demonstrated:\n\n* Conversion of [GIMP](https://www.gimp.org/) authored image assets (*`.xcf`) into `.png`, `.iff` and `.raw` (interleaved) formats\n* Compression ('packing') or raw assets using the '`zx0`' format\n* Generation of palette (`COLORxx` register) data for image assets in copper list format\n* Generation of a Workbench 'tool' icon (*.info) for the main executable from a GIMP image (*.xcf)\n* Host compilation of assembler (`vasm`) and linker (`vlink`) tools included.\n* Building to a [UAE](https://en.wikipedia.org/wiki/UAE_(emulator)) emulated hard drive (`dh0`) folder\n* Building of a ***bootable*** AmigaDOS floppy disk format image (`ADF`) file.\n* A Unix [Makefile](#makefile) to automate building on the host machine\n* A [GitHub Actions (GHA)](https://docs.github.com/en/actions)[workflow](#github-actions-workflow)\nfor CI/CD automated building in the the cloud.\n\n## Limitations / TODO ##\n\n* Only RAW files with 'interleaved' bitplanes data are generated (no 'back-to-back' support)\n* Only images for low resolution (non-EHB) mode apps are supported.\n* Only `zx0` compression/packing support.\n* No support for attached sprites palette generation\n* No special treatment for AGA\n* Bare bones 'no frills' bootable AmigaDOS ADFs. i.e. no loading messages etc.\n* Only a target executable ('tool' type) icon is generated. No custom disk icon.\n\n## Demo App ##\n\nThis repo contains source code for a simple Amiga demo using Bitplanes (playfield), Blitter objects (BOBs) and Sprites.\n\nThis demo was made using samples of [example code](https://www.edsa.uk/blog/downloads) from the excellent book\n['Bare-Metal Amiga Programming'](https://www.edsa.uk/blog/bare-metal-amiga-programming)\nby E. Th. van den Oosterkamp, and used under his permissive license terms.\n\nThis demo also includes m68k asm `zx0` decompression code from [`salvador`](https://github.com/emmanuel-marty/salvador) by Emmanuel Marty, also used under permissive license terms.\n\nThe app was also developed in the equally excellent\n[Amiga Assembly](https://marketplace.visualstudio.com/items?itemName=prb28.amiga-assembly)\nextension for [Visual Studio Code](https://code.visualstudio.com/) (VSCode).\nVSCode is not required for this workflow but this repo structure matches the example project\nand aims to be compatible with its structure. e.g. the emulated hard drive `uae\\dh0` is the\ndestination for the built binary.\n\n## Requirements ##\n\nA host Linux environment is expected. This project has been developed under Debian based Linux x86_64 distros (e.g. Ubuntu)\nOther environments may need some modifications to run.\n\nSome additional tools are required to be installed and made available in the `PATH`.\nThese are automatically installed by the [GHA workflow](#github-actions-workflow)\nbut will need to be installed manually to run on a local host machine.\n\n### GIMP ###\n\n[GIMP](https://www.gimp.org/) is required to convert GIMP native (`*.xcf`)\n[indexed colour](https://en.wikipedia.org/wiki/Indexed_color) mode image asset files into\nan intermediary [`PNG`](https://en.wikipedia.org/wiki/PNG) format.\n\nGIMP may already be installed on your Linux distro. If not it can be installed either through\nyour distro package manager (e.g. Debian `apt`:)\n\n```sh\nsudo apt install gimp\n```\n\nor as a flatpak from [FlatHub](https://flathub.org/apps/org.gimp.GIMP)\n\n### ipng2iff ###\n\n[ipng2iff](https://github.com/m0ppers/ipng2iff) is used to create [`ILBM`/`IFF`](https://en.wikipedia.org/wiki/ILBM)\nimage files as used on the Amiga from [`PNG`](https://en.wikipedia.org/wiki/PNG) source files exported from GIMP.\n\n`ipng2iff` has to be built from source. To do so requires you have a working\n[RUST](https://www.rust-lang.org/) environment setup.\n\n```sh\ngit clone https://github.com/m0ppers/ipng2iff.git\ncd ipng2iff\ncargo build -r\n```\n\nOnce `ipng2iff` has built, you need to move it to somewhere where it can be found in your `$PATH`. e.g.\n\n```sh\nsudo cp target/release/ipng2iff /usr/local/bin\n```\n\n### ilbmtoppm ###\n\n`ilbm2ppm` is used to fetch metadata about IFF image files.\nIt is part of the [`netpbm`](https://netpbm.sourceforge.net/) toolkit.\n\n`netpbm` can be installed using your package manager. e.g. for Debian `apt`:\n\n```sh\nsudo apt install netpbm\n```\n\n### salvador ###\n[salvador](https://github.com/emmanuel-marty/salvador) is used to compress `*.raw` images into `*_raw.zx0` packed files in the `zx0` format to help save space.\n\n`salvador` has to be built from source.\n```sh\ngit clone https://github.com/emmanuel-marty/salvador\ncd salvador\nmake\n```\n\nOnce `salvador` has built, you need to move it to somewhere where it can be found in your `$PATH`. e.g.\n\n```sh\nsudo cp salvador /usr/local/bin\n```\n\n### amitools ###\n\n[amitools](https://pypi.org/project/amitools/) is used to create floppy disk (`ADF`) images using\n[xdftool](https://amitools.readthedocs.io/en/latest/tools/xdftool.html)\n\nTo install amitools, first make sure you have a working [python3](https://www.python.org/) environment.\nThen amitools can be installed with these commands:\n\n```sh\npython3 -m pip install --upgrade pip setuptools wheel\npython3 -m pip install amitools\n```\n\n## GIMP Source Image Requirements ##\n\nYour source (`.xcf`) GIMP files should be using\n[indexed color](https://en.wikipedia.org/wiki/Indexed_color) mode, not 'RGB'.\nYou can convert an RGB image into indexed using GIMP from the menu:\n\n```none\nMenu-\u003eImage-\u003eMode-\u003eIndexed...\n```\n\nA dialog will be presented allowing you choose the number of colours and whether you wish to use dithering etc.\n\n## Naming Conventions ##\n\nWhilst not absolutely required, the workflow will work better if you stick to certain naming conventions\nfor your image assets.\n\nBy default the copper list output of palette data will begin at colour palette index 0\n(`COLOR00`/`0xdff180`) and proceed incrementally. This behaviour can be changed by using naming conventions\nfor the source (`.xcf`) image files:\n\n### Dual Playfields ###\n\nIf you are developing a dual-playfield app, it's likely that for images destined for playfield 2 you\nwill need the palette to start from the 'even bitplanes' palette of `COLOR08`/`0xdff190`\n(See the [HRM](https://amigadev.elowar.com/read/ADCD_2.1/Hardware_Manual_guide/node007A.html)\nfor more details)\n\nThis can be achieved by including the text '`pf2`' somewhere in your image source filename.\n\n### Sprites ###\n\nSprites 0-7 operate in pairs and share a palette of 4 colours. As per the\n[HRM](https://amigadev.elowar.com/read/ADCD_2.1/Hardware_Manual_guide/node00B7.html)\n\n```ascii\n                 16  Unused   00  |\n                 17  Color 1  01  |\n                 18  Color 2  10  |-- Sprites 0 and 1\n                 19  Color 3  11 _|\n                 20  Unused   00  |\n                 21  Color 1  01  |\n                 22  Color 2  10  |-- Sprites 2 and 3\n                 23  Color 3  11 _|\n                 24  Unused   00  |\n                 25  Color 1  01  |\n                 26  Color 2  10  |-- Sprites 4 and 5\n                 27  Color 3  11 _|\n                 28  Unused   00  |\n                 29  Color 1  01  |\n                 30  Color 2  10  |-- Sprites 6 and 7\n                 31  Color 3  11 _|\n```\n\nBy including e.g. `spr0` in your filename the copper list palette will be output starting at the appropriate colour index.\nNote, that for each sprite pair only one palette file is generated. In the case of multiple source files for the same sprite\npair, the last one to be processed will be used as the source for palette data.\n\n## Makefile ##\n\nThe [`Makefile`](./Makefile) is invoked by the command:\n\n```sh\nmake \u003cTARGET\u003e\n```\n\nWhere `\u003cTARGET\u003e` is an optional specified component. If `\u003cTARGET\u003e` is not specified it will default to '`all`'\nThe various useful targets are described in the table below\n\n| Target    | Description |\n|-----------|-------------|\n| `all`     | Convert assets, build tools, assemble source `.s` files into `.o` object files and link program into `uae/dh0`. |\n| `adf`     | Everything in the `all` target PLUS generation of icons and floppy disk image (ADF) file. |\n| `assets`  | Only converts image assets (and generates palette include files) |\n| `icons`   | Only converts icons |\n| `tools`   | Only builds the tools (`vasm` \u0026 `vlink`) |\n\nBy default the target will not include `linedebug` data and will be stripped of symbols. To preserver these pass `DEBUG=1`:\n\n```sh\nmake \u003cTARGET\u003e DEBUG=1\n```\n\nThe Makefile also supports a set of 'clean-up' targets to remove files:\n\n| Target            | Description |\n|-------------------|-------------|\n| `clean`           | Removes built target program and `.o` object files.|\n| `clean_adf`       | Removes the floppy disk image (ADF) file. |\n| `clean_assets`    | Removes converted image asset files (and generated palette include files) |\n| `clean_icons`     | Removes converted icon files |\n| `clean_tools`     | Removes object and executable files for the tools (`vasm` \u0026 `vlink`)|\n| `clean_all`       | Removes all of the above|\n\n## Image Asset Conversion Script ##\n\nThe image asset conversion script (`convert_assets_to_raw.sh`) is located in the [scripts](./scripts/) directory.\nIt's used by the `Makefile`, but it can also be used standalone to do more selective conversions if required:\n\nPassing `-h` (or `--help`) to the script shows usage information:\n\n```none\n$ ./scripts/convert_assets_to_raw.sh -h\nusage: convert_assets_to_raw.sh [options] [input file]\n\nOptions:\n \n -a,--asset-dir \u003cdir name\u003e\n     Use dir \u003cdir name\u003e to find source assets and place output assets.\n     Defaults to ./assets \n -d,--delete-ints\n     Delete intermediate files (PNGs \u0026 IFFs). \n -i,--include-dir \u003cdir name\u003e\n     Use target dir \u003cdir name\u003e for palette include files. \u003cdir name\u003e MUST exist.\n     Defaults to same dir as --asset-dir \n -n,--dry-run\n     Show what would be done only. Do not actually [over]write or delete any output files. \n -p,--png-iff\n     Include generation of IFF files from PNGs. \n -r,--iff-raw\n     Include generation of RAW bitplane data files from IFFs. \n -s,--inc-pal\n     Include generation of palette ASM include code files from IFFs. \n -x,--xcf-png\n     Include generation of PNG files from XCFs. \n```\n\nIf no `input_file` is specified, the script will works as a wildcard selecting all applicable files in the specified (or default) 'assets' directory.\n\n## Icon Conversion Script ##\n\nThe icon asset conversion script (`amiga-icon-converter.py`) is located in the [scripts](./scripts/) directory.\nIt's used by the `Makefile`, but it can also be used standalone to do more selective conversions if required:\n\nPassing `-h` (or `--help`) to the script shows usage information:\n\n```none\n$ ./scripts/amiga-icon-converter.py -h\nusage: amiga-icon-converter.py [-h] [--type {1,2,3,4,5,6,7,8}] [--width WIDTH] [--height HEIGHT] [--output OUTPUT] [--palette {1,2}] input_image\n\nConvert image to Amiga Workbench icon\n\npositional arguments:\n  input_image           Path to input image file\n\noptions:\n  -h, --help            show this help message and exit\n  --type {1,2,3,4,5,6,7,8}\n                        Icon type (1: Disk, 2: Drawer, 3: Tool, 4: Project, 5: Trashcan, 6: Device, 7: Kickstart ROM, 8: Appicon, default: 3)\n  --width WIDTH         Icon width in pixels (default: 48)\n  --height HEIGHT       Icon height in pixels (default: 48)\n  --output OUTPUT       Optional output path for the .info file\n  --palette {1,2}       Palette version (1 for 1.x, 2 for 2.x, default: 2)\n```\n\nIf no output file is specified with `--output` the output will have the same name and path as the `input_image` but the file extension changed to `.info`\n\n## GitHub Actions Workflow ##\n\nThis repository includes a [GitHub Actions](https://docs.github.com/en/actions) (GHA)\n[workflow](./.github/workflows/amiga_demo.yml) for automated build and ADF packaging\nin the cloud using a GHA hosted\n[Ubuntu 24.04 (LTS) runner image](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md).\nSuccessful build artifacts (ADFs) can be downloaded from the\n[Actions tab](https://github.com/neildavis/amiga_asmdev_workflow/actions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneildavis%2Famiga_asmdev_workflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneildavis%2Famiga_asmdev_workflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneildavis%2Famiga_asmdev_workflow/lists"}