Skip to content

README.md

Latest commit

 

History

History
309 lines (247 loc) · 13.3 KB

README.md

File metadata and controls

309 lines (247 loc) · 13.3 KB
Raw

mg-amiga: this fork adds AmigaOS 3.x support, see amiga/README.md. Binaries: the releases here and Aminet (text/edit/mg-amiga.lha).

Micro (GNU) Emacs

License Badge Release Badge GitHub Status Coverity Status

Contents

Introduction

Mg is a Micro Emacs clone created in 1987, based on the original MicroEMACS v30 released by Dave Conroy in 1985. The name, "Micro GNU Emacs", was disputed early on by the FSF, so today it simply goes by mg. This software is fully free and in the public domain.

The intention is to be a small, fast, and portable Emacs-like editor for users who cannot, or do not want to, run the real Emacs for one reason or another. Compatibility with GNU Emacs is key for Mg, separating it from other ErsatzEmacs clones, because there should never be any reason to learn more than one Emacs flavor.

For a brief overview to what differs between upstream OpenBSD Mg and what features this project has added, see below.

Tip

Try the latest release, use the tarball with a version in the name and a sha256 checksum next to it, avoid GitHub generated links! Releases come with a configure script, so you don't need autotools. Only a C compiler, make and you're set to go.

Usage

When Emacs was born keyboards had a Meta key. Accessing functions with Meta combinations today is usually the same as holding down the Alt key, or tapping Esc once.

Other editors use short forms like Ctrl-V or ^V, in Emacs this is written C-v. Some usage examples:

Key Short Example Description
Meta M- M-x Hold down Alt and tap x
Ctrl C- C-g Hold down Ctrl and tap g
Ctrl C- C-x C-c Hold down Ctrl then tap x and c

To access the built-in Quick Help, press C-h q, meaning: hold down Ctrl and tap h, then release Ctrl and tap q. The - has a meaning, as you can see.

Building

This project is completely self hosting. However, by default you need a termcap library, like Ncurses, to provide APIs like: setupterm(), tgoto(), and tputs().

Tip

See below for how to build without Ncurses.

With termcap/terminfo/curses

On recent Debian/Ubuntu based systems libtinfo-dev can be used, on older ones the include file term.h is missing, so libncurses-dev must be used instead:

sudo apt install libtinfo-dev

or

sudo apt install libncurses-dev

On other systems you have to install the full Ncurses library instead, on RHEL, CentOS, and Fedora:

sudo yum install ncurses-devel

or

sudo dnf install ncurses-devel

On macOS you need the Xcode command line tools and headers:

xcode-select --install

Then build Mg from the unpacked release tarball:

./configure
make
sudo make install

Note

This installs to /usr/local/bin, next to any mg from your distro in /usr/bin. If UTF-8 text shows up as octal escapes like \303\251, run command -v mg to check which one you are starting.

Without curses, completely stand-alone

make clean
./configure --without-curses
make
sudo make install

Building from GIT

Users who checked out the source from GitHub must run ./autogen.sh first to create the configure script. This requires GNU autotools to be installed on the build system.

There are several options to the configure script to disable features, e.g., to reduce the size, or remove features if you want to be on par with the official Mg. By default, all below features are enabled:

./configure --help
[..]
--disable-autoexec   Disable auto-execute support
--disable-cmode      Disable C-mode support
--disable-compile    Disable C compile & grep mode, used by C-mode
--disable-cscope     Disable Cscope support
--disable-ctags      Disable ctags(1) support, required by Cscope
--disable-dired      Disable directory editor
--disable-regexp     Disable full regexp search
--disable-syntax     Disable syntax highlighting and comment-dwim
--disable-togglenl   Disable toggle-newline-prompt extension (not in OpenBSD)
--disable-all        Disable all optional features
[..]
--with-modes=LIST    File modes to build, default: all
--without-modes      Build no file modes
--with-startup=FILE  Init file to run at startup if ~/.mg is missing
--with-mglog         Enable debugging to log file, default: ./log/*.log
--without-curses     Build without curses/termcap, default: auto

The file modes are picked with --with-modes, a list separated by commas or spaces. Each name builds one mode, which is turned on for the files listed, and can be turned on by hand with its M-x command:

Name Mode Files
cmake cmake-mode CMakeLists.txt, *.cmake
conf conf-mode *.conf, *.ini, *.toml, systemd units, fstab, ssh_config, .gitconfig, ...
diff diff-mode *.diff, *.patch, *.rej
git git-commit-mode COMMIT_EDITMSG, MERGE_MSG, TAG_EDITMSG, git-rebase-todo, ...
m4 m4-mode configure.ac, configure.in, *.m4
make makefile-mode Makefile, Makefile.am, Makefile.in, *.mk, ...
markdown markdown-mode *.md, *.markdown
python python-mode *.py, scripts run by python
sh shell-script-mode *.sh, .bashrc, .profile, scripts run by sh, bash, ...
text text-mode *.txt, README, NEWS, TODO, ...
yaml yaml-mode *.yml, *.yaml, .clang-format, .yamllint

C is not in the list, since C mode has its own switch, --disable-cmode. For example, a build with only the modes for a small system's shell scripts and configuration files:

./configure --with-modes=sh,conf

Without --disable-syntax the modes color what they recognize; without syntax highlighting they still set up indentation, tabs and fill for their files.

To build the smallest possible mg, with many features removed:

./configure --disable-all --enable-size-optimizations
make
sudo make install-strip

To build a completely static mg with all features:

./configure LDFLAGS="-static"
make
sudo make install-strip

Docker

Alpine Linux based Docker container images are available from GitHub:

docker pull ghcr.io/troglobit/mg:latest

To edit files from your host's $HOME, map it to the container's /root and run:

docker run -ti -v $HOME:/root ghcr.io/troglobit/mg:latest

This supports reading your ~/.mg and it even takes arguments on the command line. Both quick help and the tutorial are bundled.

History

The history is long and intertwined with other MicroEMACS spin-offs but goes something like this:

  • Nov 15, 1985: MicroEMACS v30 released to mod.sources by Dave G. Conroy
  • Mar 3, 1987: First Release (mg1a) via comp.sources.unix
  • May 26, 1988: Second release: (mg2a) via comp.sources.misc
  • Jan 26, 1992: Linux port released by Charles Hedrick. This version later makes its way onto tsx-11, Infomagic, and various other Linux repositories.
  • Feb 25, 2000: First import into the OpenBSD tree, where it is currently maintained with contributions from many others.
  • May 8, 2016: Import from OpenBSD 5.9 to GitHub
  • May 15, 2016: Mg v3.0, first port back to Linux, by Joachim Wiberg
  • Jul 22, 2018: Mg v3.1, removed libite dependency, by Joachim Wiberg
  • Aug 26, 2018: Mg v3.2, now fully portable1, by Joachim Wiberg
  • Dec 11, 2019: Mg v3.3, misc fixes and new features from OpenBSD
  • Aug 23, 2020: Mg v3.4, new modeline, quick-help, support for gzipped files, and building without termcap/Ncurses, by Joachim Wiberg
  • Oct 17, 2021: Mg v3.5, support for Solaris/Illumos based UNIX systems tested on OmniOS and OpenIndiana, sync with Mg from OpenBSD 7.0
  • Apr 10, 2023: Mg v3.6, sync with OpenBSD, improved ctags support
  • Aug 13, 2023: Mg v3.7, sync with OpenBSD, improved usability
  • Jul 10, 2026: Mg v4.0, initial UTF-8 support by Joachim Wiberg
  • Sep 7, 2026: Mg v4.1, Unicode 17 support and lots of new modes
  • Oct 7, 2026: Mg v4.2, GNU Emacs commands, minibuffer editing and history, secure mode, and optional modes for a small build

See the source distribution for the list of AUTHORS.

Origin & Features

This project is derived from, and tracks, OpenBSD Mg, which is the best (maintained) source of the original Micro Emacs based on mg2a. The intention of this project is to develop new usability features and remain friendly to porting to resource constrained systems.

New features include, but are not limited to:

  • UTF-8 support: multibyte characters can be typed, displayed, and edited in UTF-8 locales, with double-width CJK taking two columns
  • Syntax highlighting in buffers with a language mode, c, cmake, conf, diff, git-commit, m4, makefile, markdown, python, shell-script, and yaml, toggled with M-x font-lock-mode. The mode follows the file name, or the #! line, and sets the buffer up for it: hard tabs for makefiles, spaces for python and YAML
  • M-; comments code out and back in, comment-dwim as in GNU Emacs, with the comment syntax of the buffer's mode
  • Line wrap with M-x line-wrap-mode: a line too long for the window continues on the rows below instead of being truncated at the edge
  • Line numbers in a gutter with M-x display-line-numbers-mode
  • Buffer cycling with C-x left and C-x right, most recently used first
  • A minibuffer that edits like a buffer, the same keys for word and line motion, with a history per kind of prompt on Up, Down, M-p and M-n
  • sort-lines, transpose-lines, whitespace-cleanup, rename-buffer, and the names GNU Emacs uses today, like kill-ring-save, in M-x
  • text-mode for prose, which turns on auto-fill-mode for *.txt, README, and the files a source tree keeps without a suffix
  • git-commit-mode for COMMIT_EDITMSG and its siblings, with C-c C-c to finish the commit, C-c C-k to cancel it, and C-c C-s to sign off
  • Visual mark mode: the region between mark and dot is shown in reverse video, like transient-mark-mode in GNU Emacs
  • Marking text with Shift + arrow keys, or a page at a time with Shift + PgUp/PgDn
  • Side by side windows with C-x 3, split-window-horizontally
  • Window movement with M-arrow keys, resize with M-S-arrow keys, and C-x + to balance them
  • Smart Tab indent in: c, python, and shell-script modes
  • Emacs-like modeline naming the major mode, with (row,col) and display-time-mode
  • A secure mode, -S, and a single-file mode, -s, for use as the editor of a restricted shell
  • Support for building without curses, using termios + escape seq.
  • Pick the file modes to build with --with-modes, or leave out syntax highlighting with --disable-syntax, for a small editor
  • Support for exhuberant/universal ctags tags file format
  • Built-in *quick* help using C-h q
  • Tutorial accessible using C-h t
  • Support for Ctrl-cursor + Ctrl-PgUp/PgDn like Emacs
  • Support for M-x no-tab-mode and M-x version
  • Support for opening gzipped text files in read-only mode

Please report any bugs and problems using the GitHub issue tracker https://github.com/troglobit/mg/issues

Footnotes

  1. This project has been extensively tested on Debian GNU/Linux, Ubuntu, CentOS, Fedora, Alpine Linux, Solaris/Illumos based systems like OmniOS, FreeBSD, NetBSD, OpenBSD, DragonFly BSD, Apple macOS >= 10.10, Cygwin, MSYS2, as well as embedded Linux systems using musl libc and uClibc-ng. ↩