====================
DASM 2.20.16 readme
====================

    Welcome to DASM, a versatile macro assembler with support for several
    8-bit microprocessors including MOS 6502 & 6507; Motorola 6803, 68705,
    and 68HC11; Hitachi HD6303 (extended Motorola 6801) and Fairchild F8.

    Download the latest compiled & packaged version of DASM from here:
    https://github.com/dasm-assembler/dasm/releases/latest

    For a comprehensive User Guide to using DASM, grab:
    https://raw.githubusercontent.com/dasm-assembler/dasm/master/docs/dasm.pdf    

    Other documentation is at:
    https://raw.github.com/dasm-assembler/dasm/master/doc/dasm.txt

    This file describes the DASM source distribution, how to compile DASM, 
    and where to get more information.

    DASM's homepage is https://dasm-assembler.github.io/

---------------
Binary Releases
---------------

    In case you're running Windows, macOS or Linux and just want to download 
    and use DASM, please go directly to the releases:
    https://github.com/dasm-assembler/dasm/releases
    
----------------
The Distribution
----------------

    The DASM distribution contains the following important files and
    directories of interest to all users:

        docs/            Documentation and manuals
        docker/          Contains files & instructions to create a docker
                         image to run a 'dasm build machine' container
        machines/        Support files for various 8-bit machines
        LICENSE          GNU General Public License
        NEWS             Recent changes to DASM
        README           The file you are reading right now :-)

    In addition, developers are going to be interested in the following
    files and directories:

        src/        Source code for DASM and related tools
        test/       Test cases for DASM and related tools
                    (as of release 2.20.11 the test framework is incomplete)
        bin/        This is were the compiled executables for DASM and
                    related tools will be placed after you do a 'make'
        research/   A directory where we keep experiments
        ChangeLog   Source level changes to DASM
        Makefile    Makefile to build DASM executables, run tests, and
                    create distributions

    Even more files for developers are available from the DASM GitHub
    repository, see https://github.com/dasm-assembler/dasm for details.

---------
Compiling
---------

    If you are using DASM on a Unix system, you should be able to simply
    give the command

        make

    in the root directory of the DASM distribution and DASM should build.
    A bin/ directory containing DASM executables will be created as part
    of this process. You can also give the command

        make test

    to run all the test cases that come with the distribution. Note that
    as of release 2.20.11 the test framework is incomplete and probably
    only remotely comprehensible for developers. :-/ The often-used

    DASM has been built and tested successfully on recent versions of Linux,
    macOS, BSD and Windows.

    If you have successfully built and tested DASM on a different machine
    or operating system, we would love to hear about it.

    Build note: object files are placed in src/.objs/<OS>/ so that the
    same source tree can be built for macOS and Linux simultaneously
    without the object files clobbering each other.

----------
Using DASM
----------

    The simplest way to get a brief introduction to DASM is to run the
    bin/dasm executable without options, which will print a short help
    message summarizing all available options.

    For a comprehensive User Guide to using DASM, grab:
    https://raw.githubusercontent.com/dasm-assembler/dasm/master/docs/dasm.pdf    

    Documentation for using DASM to produce code for the F8 processor
    is currently in the directory machines/channel-f/ but will be
    integrated into the main documentation in the future.

    Bugs? Feature requests?
    Please report bugs or feature requests on our dasm project page.
    See https://github.com/dasm-assembler/dasm
    All versions of dasm are written in C. If you want to contribute 
    we encourage you to fork dasm and send us pull requests!

    There is also a vibrant community of developers writing games and
    demos for the Atari 2600 VCS using DASM. The mailing lists for the
    Stella emulator are a particularly useful resource for DASM users,
    not only those intent on programming for the VCS.

---------------
Security & Safety
---------------

    Release 2.20.16 included a thorough audit and repair of memory safety
    and correctness issues across the codebase. Fixes include:

    - Buffer overflows in parse(), cleanup(), and outlistfile() replaced
      with bounds-checked snprintf/AVBUF_WRITE equivalents
    - Heap buffer overflow in asmerr() when pass exceeds nMaxPasses
      (triggered by deeply chained forward references)
    - Use-after-free in the small allocator: small_free_all() now resets
      the internal cursor so subsequent small_alloc() calls do not touch
      freed memory
    - Memory leaks in v_incbin() (SYMBOL list freed on every pass)
    - Divide-by-zero in v_align() on zero alignment value
    - Signed integer overflow UB in left-shift operations (exp.c, ops.c)
    - Non-literal format strings passed to fprintf in asmerr()
    - Wrong memset byte count for bStopAtEnd array
    - getc() return value stored as unsigned in getwlh() (ftohex, ftobin),
      causing garbage output on truncated input; ftohex now opens files
      in binary mode to avoid text-mode mangling on Windows
    - Missing include guards on asm.h (caused duplicate enum errors)
    - symbols.h rewritten to match the actual symbols.c implementation
    - panic() declared in errors.h so all translation units see the
      prototype; implicit-declaration warnings on Linux eliminated

    The codebase was also reformatted to K&R style throughout.

--------
Legalese
--------

    the DASM macro assembler (aka small systems cross assembler)

    Copyright (c) 1988-2002 by Matthew Dillon.
    Copyright (c) 1995 by Olaf "Rhialto" Seibert.
    Copyright (c) 2003-2008 by Andrew Davie.
    Copyright (c) 2008-2015 by Peter H. Froehlich.
    Copyright (c) 2019-2026 by the DASM team.

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.
 
    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


-------------------------
GITHUB building a Release
-------------------------


    Artifact names are now unique per platform (dasm-windows, dasm-macos,
    dasm-linux) — the old workflow used the same name for all three which
    would conflict in parallel runs

    Added a release job that only runs on v* tag pushes; it downloads all
    three artifacts, zips each binary, and creates a GitHub release as a
    draft

    To cut a release:

        git tag v2.20.16
        git push origin v2.20.16

    That triggers the CI. All three platforms build and test in parallel,
    then the release job assembles dasm-v2.20.16-windows.zip,
    dasm-v2.20.16-macos.zip, and dasm-v2.20.16-linux.zip and creates a
    draft release on GitHub. You then go to the releases page, paste your
    release notes, and hit Publish.

    The draft step is intentional — gives you a chance to review and add
    notes before it goes public.