Metadata-Version: 2.4
Name: qtarmsim
Version: 2.0.2
Summary: Easy to use graphical ARM simulator
Project-URL: Homepage, https://lorca.act.uji.es/project/qtarmsim/
Author-email: Sergio Barrachina Mir <barrachi@uji.es>
License: GPLV3+
Keywords: ARM,assembler,debugger,disassembler,simulator
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Assemblers
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Disassemblers
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.10
Requires-Dist: pyside6>=6.10
Requires-Dist: pywin32>=1.0; platform_system == 'Windows'
Requires-Dist: typing-extensions>=4.0
Description-Content-Type: text/x-rst

QtARMSim
========

QtARMSim is an easy to use graphical ARM simulator. It provides an easy to use multiplatform ARM emulation environment that has been designed for Computer Architecture introductory courses.

The ARMSim ARM simulator, Copyright (c) 2014-2020 by Germán Fabregat, is bundled with QtARMSim. Inside the ``src/qtarmsim/armsim`` directory the next implementations can be found:

- The original stand-alone ARMSim simulator written in Ruby (in ``armsim_ruby``).
- A transpiled to Python version of the previous one (in ``armsim_python``).
- A modularized Python version of ARMSim (in ``armsim_module``).


1. Running (and installing) QtARMSim
------------------------------------

Starting with version 2.0.0, it is not necessary to install QtARMSim from PyPI, as QtARMSim stand-alone executables are provided for Windows, Ubuntu, and macOS. These executables can be downloaded from the `QtARMSim home page <https://lorca.act.uji.es/project/qtarmsim>`_.

In addition to this, if you have the `Nix package manager <https://nixos.org/download/>`_ configured to allow the experimental CLI features, then you can also execute the latest version of QtARMSim on GitHub with::

    $ nix run github:barrachi/qtarmsim

If you have installed the `UV python package manager <https://docs.astral.sh/uv/>`_, then you can also execute the latest version of QtARMSim on PyPI with::

    $ uvx qtarmsim


2. Installing QtARMSim from PyPI
--------------------------------

Although it is more convenient to directly install the stand-alone executables provided in `QtARMSim home page <https://lorca.act.uji.es/project/qtarmsim>`_, it is also possible to install QtARMSim from the `Python Package Index (PyPI) <https://pypi.org/>`_

To install QtARMSim from PyPI, you will need to also install its dependencies. QtARMSim depends on: `Python 3 <https://www.python.org/>`_; and `Qt for Python (PySide6) <https://wiki.qt.io/Qt_for_Python>`_. The ARM simulator (ARMSim) is bundled with QtARMSim, as is the `GNU GCC Arm toolchain <http://gcc.gnu.org/>`_.

Therefore, the required dependencies are:

- `Python 3 <https://www.python.org/>`_, and
- `Qt for Python (PySide6) <https://wiki.qt.io/Qt_for_Python>`_

The following sections explain how to install QtARMSim and its
dependencies on **GNU/Linux**, **Windows**, and **macOS**.


2.1 Installing QtARMSim on GNU/Linux
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you want to install QtARMSim on GNU/Linux instead of using the GNU/Linux stand-alone executable from `QtARMSim home page <https://lorca.act.uji.es/project/qtarmsim>`_, follow the next instructions.

As most GNU/Linux distributions provide packages for ``Python3``, this can be installed via the system’s package manager. ``QtARMSim`` (and ``PySide6``), on the other hand, can be installed using different ``pip`` variants.

**Example: Installation on Ubuntu**

First, install the next required packages:

.. code-block:: shell-session

    $ sudo apt install pipx
    $ pipx ensurepath

Then, for a single-user installation:

.. code-block:: shell-session

    $ pipx install qtarmsim

Or for a system-wide installation:

.. code-block:: shell-session

    $ sudo pipx ensurepath --global
    $ sudo pipx install --global qtarmsim

*Note:* If the ``--global`` option is not recognized, read the ``pipx`` documentation or search for a workaround. This drawback should be solved with something similar to:

.. code-block:: shell-session

    $ sudo pipx install pipx  # Installs a newer version of pipx on the root home
    $ sudo apt remove pipx    # Removes the older system pipx
    $ sudo bash
    # ~/.local/share/pipx/venvs/pipx/bin/pipx install pipx --global
    # ~/.local/share/pipx/venvs/pipx/bin/pipx ensurepath --global
    # exit
    $ sudo pipx install --global qtarmsim  # The newer version should support --global


2.2 Installing QtARMSim on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you want to install QtARMSim on Windows instead of using the Windows stand-alone executable from `QtARMSim home page <https://lorca.act.uji.es/project/qtarmsim>`_, follow the next steps:

1. Download a 64-bit Python installer from the `Windows official Python website <https://www.python.org/downloads/windows/>`_ (or from the MS Windows store). Make sure to select **"Add python.exe to PATH"** during installation. **Select Python 3.10 or newer** (check the `Qt for Python compatibility matrix <https://wiki.qt.io/Qt_for_Python>`_ for the latest supported versions).

2. Open a console (``cmd`` or ``PowerShell``) and run the following commands:

   .. code-block:: powershell

       pip3 install qtarmsim           # to install qtarmsim
       post_install_qtarmsim           # to create start menu entry and shortcuts


2.3 Installing QtARMSim on macOS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you want to install QtARMSim on macOS instead of using the macOS stand-alone executable from `QtARMSim home page <https://lorca.act.uji.es/project/qtarmsim>`_, follow the next steps:

1. Install Python 3 from the `official Python website <https://www.python.org/downloads/>`_. Make sure you install a Python version supported by PySide6 (check the *Python compatibility matrix* in `Qt for Python <https://wiki.qt.io/Qt_for_Python>`_).

2. Open a terminal and run:

   .. code-block:: shell-session

       $ sudo -H pip3 install qtarmsim
       $ sudo post_install_qtarmsim

After installation, you can run QtARMSim by typing ``qtarmsim`` in a **new** terminal session.

**Note:** If you encounter an error stating that PySide6 is not available for your macOS version, you can install PySide6 via `MacPorts <https://guide.macports.org/#installing.xcode>`_ and then install QtARMSim without Python dependencies:

.. code-block:: shell-session

    $ sudo port install py311-pyside6   # Replace 'py311' with your Python version
    $ sudo -H pip3 install --no-deps qtarmsim
    $ sudo post_install_qtarmsim


License
-------

Copyright 2014-2026 Sergio Barrachina Mir <barrachi@uji.es>

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 3 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, see <https://www.gnu.org/licenses/>.


3rd party software acknowledgments
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The next 3rd party software is used and distributed with QtARMSim.

ARMSim: an ARM simulator, copyright Germán Fabregat Llueca, licensed
under the GPLv3+. Included under the ``qtarmsim/armsim`` directory.

`GCC, the GNU Compiler Collection <https://www.gnu.org/software/gcc/>`_,
copyright the Free Software Foundation, Inc, licensed under the GPLv3,
with the addition under section 7 of an exception described in the “GCC
Runtime Library Exception, version 3.1”
(see <https://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html>).
Binary versions targeting the ARM EABI are included under the
``qtarmsim/gcc-arm`` directory.

`Qfplib: an ARM Cortex-M0 floating-point library in 1 kbyte
<https://www.quinapalus.com/qfplib.html>`_, copyright Mark Owen,
licensed under the GPLv2. Source code
included under the ``3rdparty/`` directory. This part of the code
is only available under the GPLv2 license.

`AlphaSmart 3000 <https://www.urbanfonts.com/fonts/AlphaSmart_3000.font>`_ font,
designed by Colonel Sanders. Included under the ``src/3rdparty/`` directory.


Changelog
---------

2.0.0 (2026-06-12)
^^^^^^^^^^^^^^^^^^
- Ported the entire GUI layer to the PySide6 API >= 6.10 (Qt6).
- Added light, dark, and system colour theme support with a configurable font size.
- Bundled a new in-process ARM simulator (``armsim_module``) written in Python,
  so QtARMSim no longer requires an external Ruby or Python server to run.
- Added a backend selector in the Preferences dialog to choose between the new
  built-in module, the Python server, or the Ruby server; each backend stores its
  own command and working-directory settings independently.
- Reorganised the three simulator backends under a common ``armsim/`` directory
  (``armsim_module/``, ``armsim_python/``, ``armsim_ruby/``).
- Fixed RAM word editing in the memory view and ASCII column refresh in the dump view.
- Fixed Ctrl+C not working while the simulator is connected.
- Fixed resource leaks and robustness issues in ``ARMSimConnector`` and ``MySocket``.
- Fixed bundled GCC selection and path handling.
- Fixed a thread crash in ``ARMSimConnector`` when the armsim process terminates.
- Added a CI workflow to build standalone executables for Linux, Windows, and macOS
  on every version tag.
- Added ``flake.nix`` for ``nix run`` / ``nix develop`` support (NixOS / nix-darwin).
- Proofread and updated the built-in help and documentation.

1.0.7 (2025-10-12)
^^^^^^^^^^^^^^^^^^
- Updated PySide6 dependencies and python requirements.
- Created __main__.py so qtarmsim can be launched with python -m qtarmsim.

1.0.6 (2025-06-23)
^^^^^^^^^^^^^^^^^^
- Removed pyqtdarktheme dependency (it only supports python versions lower than 3.12).
- Edited the package documentation.

1.0.4 (2025-06-20)
^^^^^^^^^^^^^^^^^^
- Reorganized the project to use pyproject.toml and the hatchling builder.
- Updated the KDE breeze icons.
- Using pyqtdarktheme to improve the QtARMSim aesthetics.

1.0.1 (2023-11-28)
^^^^^^^^^^^^^^^^^^
- Fixed the way an ARM macOS is detected.

1.0.0 (2023-11-03)
^^^^^^^^^^^^^^^^^^
- Migrated from PySide2 to PySide6.
- Updated the bundled GNU GCC (cross) compilers and added the win64 and ARM macOS versions.
- Added the font increase and decrease functionality to the registers and memory panels.

0.5.5 (2021-10-28)
^^^^^^^^^^^^^^^^^^
- Fixed bug with macOS BigSur and PySide2.

0.5.4 (2021-05-27)
^^^^^^^^^^^^^^^^^^
- Fixed incompatibility with Ruby 3.0.

0.5.3 (2020-11-06)
^^^^^^^^^^^^^^^^^^
- Updated the installation instructions.
- A newer 64 bit GNU GCC Arm toolchain for macOS has been included.

0.5.2 (2020-06-20)
^^^^^^^^^^^^^^^^^^
- Updated the installation instructions.
- Updated post installation hook for linux.
- Post installation code reorganized to allow post_install to be installed as a script.

0.5.1 (2020-06-13)
^^^^^^^^^^^^^^^^^^
- Reformatted post_install code and added a hook for linux.
- Changed default QtARMSim icon by the SVG version.
- Moved post_install.py script outside of qtarmsim module to avoid its dependency on PySide2 (under certain circumstances, post-install is called before the PySide2 dependency is installed).

0.5.0 (2020-05-25)
^^^^^^^^^^^^^^^^^^
- Visualization improvements, especially on the trace ribbon (left area of the simulator).
- The registers at the register dock are now highlighted when a register is highlighted in the editor or in the simulator.
- Added Full Screen mode.
- Added new Compact layout. Hides everything but the registers and memory docks (which are stacked at the left) and the Edit/Simulation widget (which takes the rest of the window).
- The ARMSim path and GNU compiler path are tested on initialization. If they are no longer valid (usually due to a system python update), they are replaced by their default values.
- Improved the QtARMSim installation and integration on GNU/Linux, Windows and macOS. On GNU/Linux, the KDE expected mime type for assembler editors has been added. On Windows, a menu entry and a desktop shortcut are now created. On macOS, the qtarmsim script is automatically copied on /opt/local/bin/.
- Added a simulator output panel that displays the stdout of ARMSim (available only in debug mode).
- Fixed a bug in ARMSim due to GCC trimming the lines of the LST file at a fixed number of bytes, which under certain circumstances could lead to split a multi byte UTF-8 character and provoke an exception.

0.4.19 (2020-05-05)
^^^^^^^^^^^^^^^^^^^
- Fixed bug: 'QPaintDevice: Cannot destroy paint device that is being painted'.
- Updated ARMSim version.

0.4.18 (2020-05-05)
^^^^^^^^^^^^^^^^^^^
- Fixed bug: assigning a PIPE to armsim stdout prevented the Windows version to work properly.

0.4.17 (2020-05-04)
^^^^^^^^^^^^^^^^^^^
- Updated installation instructions for Windows systems.

0.4.16 (2019-11-08)
^^^^^^^^^^^^^^^^^^^
- Added the Show/Hide tabs and spaces functionality (on the editor contextual menu).
- Saved files are forced to end with a new line (to avoid misleading the gcc compiler if the last line ended with a TAB).
- Added zoom in and zoom out via CTRL++ and CTRL+- (CTRL+wheel already was there).
- Tab width is now correctly computed.

0.4.15 (2019-07-15)
^^^^^^^^^^^^^^^^^^^
-  Added the ``printf`` subroutine to the ARMSim firmware.

0.4.12 (2019-04-24)
^^^^^^^^^^^^^^^^^^^
- PySide2 5.12.2 has corrected the previously changed signature of QAbstractItemModel.createIndex(). The INSTALL documentation has been modified to no longer force the installation of PySide2 5.11.

0.4.11 (2019-01-21)
^^^^^^^^^^^^^^^^^^^
- PySide2 5.12 has changed the signature of QAbstractItemModel.createIndex(), as it seems that they are going to do a regression, the INSTALL documentation has been changed to force the installation of the previous 5.11.2 version of PySide2.

0.4.10 (2018-11-20)
^^^^^^^^^^^^^^^^^^^
- Added an scroll area inside the LCD Display dock widget (so that the LCD width does not force the whole simulator width).
- Changed LCD font to "AlphaSmart 3000" by Colonel Sanders.
- Added a new example of floating point operations usage, ``triangle.s``, under 'File > Examples > Floating point' menu.

0.4.9 (2018-10-16)
^^^^^^^^^^^^^^^^^^
- Changed LCD font to "1 Digit" by David Chung.
- Fixed bug that prevented code to be resized.

0.4.8 (2018-10-8)
^^^^^^^^^^^^^^^^^
- Properly acknowledging Qfplib by Mark Owen.

0.4.7 (2018-7-27)
^^^^^^^^^^^^^^^^^
- Added memory contents tooltips.
- Added new example, LCD/ascii, and revised previous ones.
- Changed the way the monospaced font is selected.

0.4.4 (2018-7-25)
^^^^^^^^^^^^^^^^^
- Migrated to Qt for Python (PySide2).
- Speeded up the filling of the simulator data.
- Added examples as a File menu entry.
- Added ARMSim tabs to separate the source code of the different ROMs.
- Added Qfplib (floating point library) API documentation to the help.
- Added UseLabels ARMSim option.
- Memory dock: first RAM is expanded by default and whenever a memory entry is modified it scrolls to its position.

0.3.16 (2018-1-17)
^^^^^^^^^^^^^^^^^^^
- Corrected typo on the restructured text format of the changelog documentation.

0.3.15 (2018-1-17)
^^^^^^^^^^^^^^^^^^^
- Added support in the simulator to showing jump labels instead of
  their addresses.
- Corrected errata on Qfp library acknowledgments.
- Removed legacy code from GlSpim.

0.3.14 (2017-11-08)
^^^^^^^^^^^^^^^^^^^
- Added SVG icon support explicitly: the toolbar icons now will be
  also shown on Windows.
- ARMSyntaxHighlighter rules are now generated only the first time.
- ARMSim:
  - Added support for floating point operations including Qfplib: an ARM Cortex-M0 floating-point library in 1 kbyte.
  - Corrected minor bug: .global declared labels generated a linking error.
  - Corrected minor bug: negative displacements on 'bl' instructions where incorrectly displayed.

0.3.13 (2017-11-02)
^^^^^^^^^^^^^^^^^^^
- Added preliminary printing support.

0.3.12 (2017-04-21)
^^^^^^^^^^^^^^^^^^^
- Changed the icon set to the KDE Breeze one.
- LCD Display not rescaling correctly on some desktop environments
  fixed.
- LCD display can now be zoomed with CTRL+mouse wheel.
- Editors and panels now honor the system default point size.
- Now the menu bar is displayed on the system menu bar on Mac OS X.

0.3.11 (2016-10-30)
^^^^^^^^^^^^^^^^^^^
- The Edit menu actions have been implemented.
- Settings values are now automatically stripped to avoid errors due
  to misplaced spaces.
- ARMSim: updated firmware to correct a bug on sdivide subroutine.

0.3.10 (2016-09-19)
^^^^^^^^^^^^^^^^^^^
- ARMSim: updated firmware to provide a signed division subroutine.

0.3.8 (2016-09-19)
^^^^^^^^^^^^^^^^^^
- Bug corrected: waiting spinner occluded File and Edit menus.

0.3.7 (2016-09-18)
^^^^^^^^^^^^^^^^^^
- Added firmware ROM that provides, among others, functions to display
  strings and numbers on the LCD display. The new memory organization
  consists of two ROM blocks and two RAM blocks. The first ROM block
  is filled with the assembled user code. The second ROM, with the
  firmware machine code. The first RAM can be used to store the user
  program data. The second RAM is used by the LCD display.
- The graphical interface now uses a thread to retrieve the memory
  contents and the disassembled code from the two ROM blocks.
- The regular expressions used to highlight the code on the editors
  have been optimized to increase the highlighting process speed.

0.3.5 (2016-09-12)
^^^^^^^^^^^^^^^^^^
- Improved the Mac OS X compatibility and added installation
  instructions for this platform.
- Changed the minimum size of the code editor container to accommodate
  lower resolution screens.
- ARMSim: (i) LSL result is now bounded to 32 bits; (ii) command
  redirection is performed explicitly to avoid an error on newer
  Windows versions; and (iii) the method used to compare whether
  memory blocks where not defined has been changed to avoid errors on
  Ruby with version >= 2.3.

0.3.4 (2016-01-21)
^^^^^^^^^^^^^^^^^^
- Added a memory dump dock widget that allows to see and edit the
  memory at byte level. It also shows the ASCII equivalent of each
  byte.
- Added a LCD display dock widget that provides a simple output
  system. It has a size of 32x6 and each character is mapped to a
  memory position starting a 0x20070000.

0.3.3 (2015-11-28)
^^^^^^^^^^^^^^^^^^
- Added a visual indication of which instructions have already been
  executed on the left margin of the ARMSim panel.
- Added automatic scroll on simulation mode in order to keep the next
  line that is going to be executed visible.
- Improved the automatic selection of a mono spaced font (previously
  selected font used ligatures).
- Fixed an error on the Preferences Dialog which prevented to select
  the ``ARMSim directory`` and the ``Gcc ARM command line`` using the
  corresponding directory/file selector dialogs.
- ARMSim: Fixed the simulation of shift instructions: only the 8 least
  significant bits are now used to obtain the shift amount.
- ARMSim.: Fixed the behavior when memory outside the current memory
  map is accessed: each wrong access now raises a memory access error.
- Bundled a reduced set of the GNU compiler toolchain. To reduce the
  package size, only those files actually required to assemble an
  assembly source code have been included.

0.3.0 (2015-06-09)
^^^^^^^^^^^^^^^^^^
- Migrated from PyQt to PySide to allow a simpler installation of
  QtARMSim.
- Developed a new source code editor based on QPlainTextEdit, though
  removing the prior QScintilla dependency, which allows a simpler
  installation of QtARMSim.
- Improved the ARM Assembler syntax highlighting.

0.2.7 (2014-11-05)
^^^^^^^^^^^^^^^^^^
- Last revision of the first functional QtARMSim implementation. This
  implementation  was used on the first semester of an introductory
  course on Computer Architecture at Jaume I University. This is the
  last version of that implementation, which used PyQt and QScintilla.
