! DISCLAIMER !
  • ■ The following projects come with absolutely no warranty of any kind.
  • ■ Whatever you do with this information is your own responsibility.
  • ■ Made for research and fun. Nothing else.
  • ■ All third-party git hosts are only used exclusively as a means to distribute the projects and are NOT the original development repos.


HEXMACS
// Custom EMACS configuration with automated package management
Table of Contents
About HEXmacs

EMACS is perhaps the most powerful tool in a programmers arsenal, though its power lies hidden deep within layers of initial complexity, as one learns the basics of the system it becomes quite apparent why an increasing amount of developers find it worthwhile to switch despite the relativelty steep learning curve.

HEXmacs organizes the emacs files into an template that comes preconfigured with fully featured development environments for the languages used in the XENOBYTE projects plus a few, general purpose utilities. To manage all these packages, HEXmacs uses a very simple script that scans the package list in /emacs.d/hexmacs-packages.el and automatically searches, downloads, installs and updates them. To configure the installed packages the /.emacs.d/custom/ folder contains the loading and configuration files ordered by package type. To include a new addon, simply add whatever custom commands the package requires and the main .emacs file will load it on startup. The main .emacs file also contains the settings for debugging, file backups and user data.

HEXmacs should work with any EMACS 25+ installation, but it is maintained for the newest stable release.

Features
  • Updated and ready for EMACS 27+
  • Fully featured development environments and setups for C, C++, lua, python, javascript, LISP, bash, PHP and more
  • Grammar & spelling correction suite for all available langauges (locale.gen)
  • Organized template based on pure EMACS LISP (no package loading dependencies at all)
  • Unobtrusive configuration that can be easily exapnded upon
  • Automatic package management
  • Smaller and faster than alternatives like spacemacs
  • Regularly updated and kept at bleeding-edge state
Configuration

The HEXmacs configuration is merely a reorganization of the vanilla EMACS setup. It first loads the main ~/.emacs file and goes through it's contents, downloading and installing the packages specified in ~/.emacs.d/hexmacs-packages and finally configuring them by loading the ~/.emacs.d/custom/ files. To remove or add custom config files simply add them to the .emacs list but beware that package loading order matters.

  • ~/.emacs
  • ~/.emacs.d/hexmacs-packages.el
  • ~/.emacs.d/custom/asm-conf.el
  • ~/.emacs.d/custom/c-conf.el
  • ~/.emacs.d/custom/company-conf.el
  • ~/.emacs.d/custom/flycheck-conf.el
  • ~/.emacs.d/custom/general-conf.el
  • ~/.emacs.d/custom/helm-conf.el
  • ~/.emacs.d/custom/interface-conf.el
  • ~/.emacs.d/custom/ivy-conf.el
  • ~/.emacs.d/custom/keys-conf.el
  • ~/.emacs.d/custom/lua-conf.el
  • ~/.emacs.d/custom/python-conf.el
  • ~/.emacs.d/custom/web-conf.el
  • ~/.emacs.d/custom/yasnippet-conf.el

Previews
HEXMACS DEMO
C/C++ SETUP
JAVASCRIPT SETUP
PYTHON SETUP
EXAMPLE BUFFER LAYOUT
Download
Installation & Setup

This installation assumes the user is running a newly installed arch or manjaro as starting point, but it works with any other UNIX distro and even Windows (not all packages are guaranteed to work in Windows, though).


Last revised: 01/01/2021


1. Install dependencies

To add grammar checking and auto correct support for a different language install its respective aspell package, hexmacs is configured to work with English, Spanish and Portuguese.

pacman -Sy
pacman -S aspell aspell-en aspell-es aspell-pt clang llvm gcc lua nodejs python-virtualenv cmake ctags python-pygments wget xwinfo xorg-xwininfo xorg-xprop xclip jansson nasm


Note that the default font isn't included, it must be manually downloaded from the dotfiles repo and installed, alternatively you can simply specify a different font while configuring the custom/interface-conf.el file.


2. Install EMACS from source
Make sure toggle configure their build with native JSON support (requires libjansson) (available as of EMACS 27)

wget https://ftp.gnu.org/pub/gnu/emacs/emacs-27.1.tar.gz
cd ~/Downloads/emacs
./autogen.sg
configure --with=json
make -j12
sudo make install


3. Install gnu-global from source

wget https://www.gnu.org/software/global/download.html
tar xvf global-.tar.gz
cd global-
./configure --with-exuberant-ctags=/usr/bin/ctags
make
sudo make install
cp gtags.conf ~/.globalrc
echo export GTAGSLABEL=pygments >> ~/.profile


4. Install BEAR from source

git clone https://github.com/rizsotto/Bear
cd bear
cmake $BEAR_SOURCE_DIR
make all
make install
make check
sudo make install


5. Install tern and JS lsp server and make a symbolic link to where EMACS requires

sudo npm i -g tern
sudo npm i -g indium
sudo ln -s ~/node_modules/bin/tern /usr/local/bin/
sudo npm i -g typescript-language-server; sudo npm i -g typescript


6. Install boxes

Boxes can be directly integrated with EMACS by selection a region and calling shell-command-on-region (C-u M-| [ | boxes -d [box style]])

git clone https://github.com/ascii-boxes/boxes
cd boxes
make
sudo cp src/boxes /usr/bin


7. Clone the HEXmacs repo and move the files to their corresponding locations

Make sure to edit ~/.zshrc to fit your system configuration.

git clone https://git.xenobyte.xyz/XENOBYTE/hexmacs/
mv hexmacs/.emacs ~/
mv -R hexmacs/.emacs.d ~/
rm -R hexmacs


8. Configure your HEXmacs installation

EMACS requires some manual configuration to properly work, the changes are mostly references to dependencies scattered throughout the system, simply read the context of the string and make sure the requested files exist.



~/.emacs

Main configuration file.

;; User details
(setq user-full-name "USERNAME")
(setq user-mail-address "EMAIL")


~/.emacs.d/hexmacs-packages.el

Contains the total package list.

// Manage extension list (extentions are autmatically downloaded and updated)


~/.emacs.d/custom/

Package loading and configuration, ordered by syntax / purpose.

asm-conf.el
c-conf.el
lsp-conf.el
company-conf.el
flycheck-conf.el
general-conf.el
helm-conf.el
interface-conf.el
ivy-conf.el
keys-conf.el
lua-conf.el
python-conf.el
web-conf.el
yasnippet-conf.el


9. Start EMACS for the first time

The first time EMACS boots it will iterate through the hexmacs-packages list and will unpack the necessary files to ~/.emacs.d/elpa. After EMACS is installed and running for the first time without errors, proceed to the configuration section.



Make sure the HEXmacs pacakge list is properly downloaded and configured, meaning that EMACS can start without errors.



10. Configuring ~/.emacs.d/custom/asm-conf.el

The assembly package depends on nasm and a local copy of the official INTEL ASM MANUAL. Download it to the ~/.emacs.d folder and rename to "x86-lookup.pdf". Lastly, install pdftotext.

wget -c https://software.intel.com/content/dam/develop/public/us/en/documents/325462-sdm-vol-1-2abcd-3abcd.pdf
mv 325462-sdm-vol-1-2abcd-3abcd.pdf ~/.emacs.d/x86-lookup.pdf
pip install pdftotext



11. Configuring ~/.emacs.d/custom/c-conf.el

Make sure the source paths are valid.

(semantic-add-system-include "/usr/include/boost" 'c++-mode)
(semantic-add-system-include "~/Qt/5.15.1/gcc_64/include/" 'c++-mode)
(semantic-add-system-include "/usr/include/c++/10.2.0" 'c++-mode)
(add-to-list 'semantic-lex-c-preprocessor-symbol-file "/usr/lib/gcc/x86_64-pc-linux-gnu/10.2.0/include/stddef.h")



12. Configuring ~/.emacs.d/custom/company-conf.el

This file shouldn't require anything modifications. If you want to add a new backend make sure to properly test it since the loading order matters.



13. Configuring ~/.emacs.d/custom/flycheck-conf.el

Remap the spell checking and language cycling hotkeys.

(global-set-key (kbd "<f6>") 'cycle-ispell-languages)
(global-set-key (kbd "<f9>") 'ispell-word)
(global-set-key (kbd "C-S-<f8>") 'flyspell-mode)
(global-set-key (kbd "<f7>") 'flyspell-buffer)
(global-set-key (kbd "C-<f8>") 'flyspell-check-previous-highlighted-word)



14. Configuring ~/.emacs.d/custom/general-conf.el

This file loads and configures all general purpose packages and their respective keybindings, edit to your liking.



15. Configuring ~/.emacs.d/custom/helm-conf.el OR ive-conf.el

Whichever your prefer, comment out the other one ~/.emacs.

;; Only enable helm or ivy
(require 'helm-conf)
;; (require 'ivy-conf)



16. Configuring ~/.emacs.d/custom/interface-conf.el

Interface settings (font, theme, cursor, toolbars, etc.) and native package configuration.



18. Configuring ~/.emacs.d/custom/lua-conf.el

No changes needed.



19. Configuring ~/.emacs.d/custom/python-conf.el

Use pip to install autopep8 and pylint.

pip install autopep8
pip install pylint



20. Configuring ~/.emacs.d/custom/web-conf.el

HTML & PHP editing should work out of the box. Javacsript setups have recently moved from tern to lsp + indium and then from company-lsp to company-capf (included in the core company package). Regardless of which JS configuration your choose (make sure to comment out their other one) you need npm to install the package dependencies. EMACS uses the exec-path-from-shell package to locate npm's global install directory.

If EMACS fails to find a dependency that your terminal doesn't, uncomment the line with the hardcoded path to the local npm binaries.

npm install -g tern indium semver node-fetch source-map p-queue chrome-remote-interface

echo 'export npm_config_prefix="$HOME/.node_modules"' > ~/.profile
echo 'export NODE_PATH="$HOME/.node_modules/bin"' > ~/.profile



21. Configuring ~/.emacs.d/custom/yasnippet-conf.el

Extract the snippets into the ~/.emacs.d/snippets directory.

git clone https://github.com/AndreaCrotti/yasnippet-snippets/
mv yasnippet-snippets/snippets ~/.emacs.d
rm -r yasnippet-snippets/



F.A.Q. & Troubleshooting

A package fails to download / install.

Make sure the package is properly named, use M-x + list-packages to get a list of all the available pacakges and C-s + the package name to validate. If this doesn't work then I suggest manually cloning the repo into the ~/.emacs.d/elpa folder. EMACS packages are constantly changing, make sure the package giving you trouble is even available in the repos.



Loading a package crashes EMACS during startup. (.emacs is ignored / default EMACS)

This usually means that the package is missing / can't find a SYSTEM dependency. If the package depends on third-party binaries (e.g. tern, indium) double check the installation path and delete the contents of the ~/.emacs.d/elpa folder so HEXmacs can refresh the configuration. This is only required if EMACS fails to boot!



The EMACS cursor looks different when running EMACS as a deamon and attaching a client than when running a server per client.

The emacsclient command doesn't start a new frame, it simply inherits the server's. Because EMACS was started as a clientless daemon it didn't start a frame in the first place. A potential workaround is to attach the cursor configuration to an non-init hook or call it after the emacsclient is initialized.



What is the project's license? Do I have to pay or credit you in any way?

The project is MIT licensed and free.

CHANGELOG

* VER 1.8 <2021-04-14 Wed 19:54> <-- CURRENT STABLE VERSION

- Isolated all LSP related configs to custom/lsp-config.el
- Removed many of lsp's unnecessary features, including lsp-ui
- Changed the company-complete hotkey to M-TAB
- Removed old comments from web-conf.el


* VER 1.77 <2021-03-29 Mon 19:04>

- Added multiple-cursors to the package list


* VER 1.7 <2021-03-21 Sun 18:01>

- Removed php-extras and ac-php
- Added lsp to php via lsp-capf


* VER 1.6 <2021-02-19 Fri 17:23>

- Removed deprecated dumb-jump package functions
- Keys M-1 to 4 currently freed


* VER 1.5 <2021-01-01 Fri 14:34>

- Purged deprecated files to clean the repo


Pre 1.5 versions have been purged to remove deprecated files.


* VER 1.3 <2021-01-01 Fri 14:34>

- Changed to an .otb version of the tewi font
- Added more helpful comments to the custom load files


* VER 1.22 <2020-11-10 Tue 20:01>

- Fixed broken links in the README
- Updated some preview images here


* VER 1.2 <2020-11-05 Thu 13:06>

- Rebranded some comments
- Removed a couple of deprecated packages


* VER 1.1 <2020-10-13 Tue 16:49>

- Updated HEXmacs to work with EMACS 27+
- Finished the installation guide HERE
- Added further comments to the configuration files


* VER 1.0 <2020-07-24 Fri 17:32>

- The EMACS configuration has been moved to its own repository.