diff --git a/README.md b/README.md new file mode 100644 index 00000000..749f1018 --- /dev/null +++ b/README.md @@ -0,0 +1,140 @@ +# MinEmacs + +[![CI-Linux](https://github.com/abougouffa/minemacs/actions/workflows/ci-linux.yaml/badge.svg)](https://github.com/abougouffa/minemacs/actions/workflows/ci-linux.yaml) +[![CI-MacOS](https://github.com/abougouffa/minemacs/actions/workflows/ci-macos.yaml/badge.svg)](https://github.com/abougouffa/minemacs/actions/workflows/ci-macos.yaml) +[![CI-Windows](https://github.com/abougouffa/minemacs/actions/workflows/ci-windows.yaml/badge.svg)](https://github.com/abougouffa/minemacs/actions/workflows/ci-windows.yaml) + +**MinEmacs** is a lightweight Emacs configuration framework. + +![MinEmacs banner](assets/images/minemacs-cover.svg) + +![MinEmacs screenshot](assets/images/minemacs-screenshot.svg) + +## Why? +I was using Doom Emacs, which I initially considered to be a remarkable software +that introduced me to the world of Emacs. Nonetheless, my experience with it +turned out to be **less enjoyable** later. + +Emacs forms the foundation of my workflow, serving as my go-to tool for various +tasks such as document writing, academic paper writing, programming in multiple +languages, email management, and staying updated with news, among other things. + +Hence, I wanted a framework that is both robust and straightforward. Doom Emacs +seemed like a suitable choice initially. However, before I started this project +back in September 2022, I encountered numerous issues with Doom Emacs. +Occasionally, after running the `doom upgrade` command, everything would cease to +function properly. These problems always seemed to arise during my busiest days, +causing unnecessary additional stress. To be frank, at that time, Doom Emacs +started to feel overly complex as a configuration framework. It incorporated a +command line interface, an extensive library with extra features, numerous +unnecessary hacks to tweak Emacs behavior for a negligible improvement in +startup time, configuration modules that tightly combined various packages in an +opinionated manner, CI commands, and even a profile manager! Each of these +features introduced extra complexity and more failure points at every layer. + +As a result, MinEmacs emerged as my personal configuration framework for Emacs, +*and it continues to serve that purpose*. I'm trying to tailor it to my specific +needs while maintaining its modularity and portability. However, I have no +intention or availability to create an alternative to Doom Emacs or Spacemacs. +While I find joy (like every other Emacser out there) in tinkering with Emacs, +MinEmacs remains just a tool that I use in my everyday work, and that I like to +share with other Emacsers. However, please note that I am not really interested +in becoming a full-time maintainer of this tool that I would only use to +maintain itself! + +## Install +Open a shell and run: + +```shell +git clone https://github.com/abougouffa/minemacs.git ~/.emacs.d && emacs +``` + +By executing this command, the repository will be cloned, and Emacs will be +launched. During the initial run, Emacs will automatically install the necessary +packages. + +> [!IMPORTANT] +> Please note that I'm using a fresh Emacs 29 built from source on a Manjaro +> Linux system. I have enabled basic [Github CI +> actions](https://github.com/abougouffa/minemacs/actions) to automatically test +> running Emacs on [Ubuntu Linux (Emacs 28 and +> 29)](https://github.com/abougouffa/minemacs/actions/workflows/ci-linux.yaml), +> [MacOS (Emacs +> 29)](https://github.com/abougouffa/minemacs/actions/workflows/ci-macos.yaml) +> and [Windows (Emacs +> 28)](https://github.com/abougouffa/minemacs/actions/workflows/ci-windows.yaml). +> These actions ensure that MinEmacs is "runnable"; with all modules enabled on +> these systems. However, more testing should be done to validate the +> configuration on systems other than Linux. +> +> I'm trying to support at least Emacs 28.2, so [I back port some of the new +> functions/macros I use to Emacs 28](core/me-backports-29.el). Furthermore, for +> Emacs 28 and earlier, MinEmacs includes the `me-compat` module which loads the +> `compat` package at early stage (just after bootstrapping `straight` and +> `use-package`), this can facilitate porting MinEmacs to earlier Emacs +> versions. However, I've never tested MinEmacs with versions earlier than 28.2, +> and I don't plan to do so! + +## Customization +To personalize MinEmacs, you can incorporate a specific set of files within the +default user configuration directory, which is located at `~/.minemacs.d`. +However, if you prefer to use a different directory, you have the flexibility to +do so by setting the `MINEMACSDIR` environment variable. + +### Main configuration files +There are two main files that can be added in the `~/.minemacs.d` directory: + +1. The `~/.minemacs.d/modules.el` file contains a list of enabled modules and a + list of disabled packages (`minemacs-core-modules`, `minemacs-modules` and + `minemacs-disabled-packages` can be set in this file). +2. The `~/.minemacs.d/config.el` file contains the user configuration and + customization, you can think of it as your `init.el`, which gets loaded at + the end of MinEmacs' `init.el`! + +This repository contains skeleton files for [modules.el](skel/modules.el) and +[config.el](skel/config.el) (under [skel/](skel)). We highly recommend following +the same structure as in the skeleton files, specially the use of +`with-eval-after-load` and `use-package` instead of using `require` directly +(`require` loads the packages immediately, which increases the startup time of +Emacs). + +### Advanced configuration files +MinEmacs provides also some advanced customization files, these files can be +used to tweak MinEmacs' behavior, add some early initialization code, make +MinEmacs runnable on older Emacs versions, etc. + +1. The `~/.minemacs.d/early-config.el` file is loaded at the end of MinEmacs' + `early-init.el`. You can use it to set up some early stuff like tweaking the + UI, overwrite the variables set by MinEmacs, and so on. +2. The `~/.minemacs.d/init-tweaks.el` file is loaded at an early stage of the + `init.el` file. You can use it to do some useful stuff before MinEmacs starts + to customize packages and load modules. This can be useful for porting + MinEmacs to an older Emacs version by providing an implementation of new + functions MinEmacs uses. See the [init.el](init.el) for more information. + +### Environment variables +You can customize MinEmacs' behavior via some environment variables. + +- `MINEMACS_DIR` or `MINEMACSDIR`: Path for MinEmacs user configuration + directory, if not set, `~/.minemacs.d/` is used. +- `MINEMACS_MSG_LEVEL`: Change message log level, from 1 (only errors) to 4 (all + messages). +- `MINEMACS_VERBOSE`: Be more verbose (useful for debugging). +- `MINEMACS_DEBUG`: Enable debugging at startup. +- `MINEMACS_ALPHA`: Set frame `background-alpha` to percentage (value from 0 to + 100). +- `MINEMACS_NOT_LAZY`: Load lazy packages immediately after loading Emacs. +- `MINEMACS_IGNORE_VERSION_CHECK`: Do not perform version check in `init.el`, + this can be useful if you use `~/.minemacs.d/init-tweaks.el` to implement the + functionalities used by MinEmacs and missing from your Emacs version. +- `MINEMACS_IGNORE_CONFIG_EL`, `MINEMACS_IGNORE_MODULES_EL`, + `MINEMACS_IGNORE_EARLY_CONFIG_EL` and `MINEMACS_IGNORE_INIT_TWEAKS_EL`: Ignore + loading, respectively, the user configuration files `~/.minemacs.d/config.el`, + `~/.minemacs.d/modules.el`, `~/.minemacs.d/early-config.el` et + `~/.minemacs.d/init-tweaks.el`. +- `MINEMACS_IGNORE_USER_CONFIG`: Ignore loading all user configuration files + (present in `~/.minemacs.d`, or directory pointed by `$MINEMACSDIR`). + +## Troubleshooting +If you experienced an issue with MinEmacs, you can check the [FAQ](FAQ.md), +check [open issues or open a new one](https://github.com/abougouffa/minemacs/issues). diff --git a/README.org b/README.org deleted file mode 100644 index 7e428ec6..00000000 --- a/README.org +++ /dev/null @@ -1,133 +0,0 @@ -* MinEmacs - -[[https://github.com/abougouffa/minemacs/actions/workflows/ci-linux.yaml][https://github.com/abougouffa/minemacs/actions/workflows/ci-linux.yaml/badge.svg]] -[[https://github.com/abougouffa/minemacs/actions/workflows/ci-macos.yaml][https://github.com/abougouffa/minemacs/actions/workflows/ci-macos.yaml/badge.svg]] -[[https://github.com/abougouffa/minemacs/actions/workflows/ci-windows.yaml][https://github.com/abougouffa/minemacs/actions/workflows/ci-windows.yaml/badge.svg]] - -*MinEmacs* is a lightweight Emacs configuration framework. The keybinding is -inspired by Doom Emacs. - -[[file:assets/images/minemacs-cover.svg]] - -[[file:assets/images/minemacs-screenshot.svg]] - -** Why? -I was using Doom Emacs, which I initially considered to be a remarkable software -that introduced me to the world of Emacs. Nonetheless, my experience with it -turned out to be *less enjoyable* later. - -Emacs forms the foundation of my workflow, serving as my go-to tool for various -tasks such as document writing, academic paper writing, programming in multiple -languages, email management, and staying updated with news, among other things. - -Hence, I wanted a framework that is both robust and straightforward. Doom Emacs -seemed like a suitable choice initially. However, before I started this project -back in September 2022, I encountered numerous issues with Doom Emacs. -Occasionally, after running the =doom upgrade= command, everything would cease to -function properly. These problems always seemed to arise during my busiest days, -causing unnecessary additional stress. To be frank, at that time, Doom Emacs -started to feel overly complex as a configuration framework. It incorporated a -command line interface, an extensive library with extra features, numerous -unnecessary hacks to tweak Emacs behavior for a negligible improvement in -startup time, configuration modules that tightly combined various packages in an -opinionated manner, CI commands, and even a profile manager! Each of these -features introduced extra complexity and more failure points at every layer. - -As a result, MinEmacs emerged as my personal configuration framework for Emacs, -/and it continues to serve that purpose/. I'm trying to tailor it to my specific -needs while maintaining its modularity and portability. However, I have no -intention or availability to create an alternative to Doom Emacs or Spacemacs. -While I find joy (like every other Emacser out there) in tinkering with Emacs, -MinEmacs remains just a tool that I use in my everyday work, and that I like to -share with other Emacsers. However, please note that I am not really interested -in becoming a full-time maintainer of this tool that I would only use to -maintain itself! - -** Install -Open a shell and run: - -#+begin_src shell -git clone https://github.com/abougouffa/minemacs.git ~/.emacs.d && emacs -#+end_src - -By executing this command, the repository will be cloned, and Emacs will be -launched. During the initial run, Emacs will automatically install the necessary -packages. - -*** ⚠ Important note -Please note that I'm using a fresh Emacs 29 built from source on a Manjaro Linux -system. I have enabled basic [[https://github.com/abougouffa/minemacs/actions][Github CI actions]] to automatically test running -Emacs on [[https://github.com/abougouffa/minemacs/actions/workflows/ci-linux.yaml][Ubuntu Linux (Emacs 28 and 29)]], [[https://github.com/abougouffa/minemacs/actions/workflows/ci-macos.yaml][MacOS (Emacs 29)]] and [[https://github.com/abougouffa/minemacs/actions/workflows/ci-windows.yaml][Windows (Emacs -28)]]. These actions ensure that MinEmacs is "runnable" with all modules enabled -on these systems. However, more testing should be done to validate the -configuration on systems other than Linux. - -I'm trying to support at least Emacs 28.2, so [[file:core/me-backports-29.el][I back port some of the new -functions/macros I use to Emacs 28]]. Furthermore, for Emacs 28 and earlier, -MinEmacs includes the =me-compat= module which loads the =compat= package at early -stage (just after bootstrapping =straight= and =use-package=), this can facilitate -porting MinEmacs to earlier Emacs versions. However, I've never tested MinEmacs -with versions earlier than 28.2, and I don't plan to do so! - -** Customization -To personalize MinEmacs, you can incorporate a specific set of files within the -default user configuration directory, which is located at =~/.minemacs.d=. -However, if you prefer to use a different directory, you have the flexibility to -do so by setting the =MINEMACSDIR= environment variable. - -*** Main configuration files -There are two main files that can be added in the =~/.minemacs.d= directory: - -1. The =~/.minemacs.d/modules.el= file contains a list of enabled modules and a - list of disabled packages (=minemacs-core-modules=, =minemacs-modules= and - =minemacs-disabled-packages= can be set in this file). -2. The =~/.minemacs.d/config.el= file contains the user configuration and - customization, you can think of it as your =init.el=, which gets loaded at the - end of MinEmacs' =init.el=! - -This repository contains skeleton files for [[file:skel/modules.el][modules.el]] and [[file:skel/config.el][config.el]] (under -[[file:skel][skel/]]). We highly recommend following the same structure as in the skeleton -files, specially the use of =with-eval-after-load= and =use-package= instead of -using =require= directly (=require= loads the packages immediately, which increases -the startup time of Emacs). - -*** Advanced configuration files -MinEmacs provides also some advanced customization files, these files can be -used to tweak MinEmacs' behavior, add some early initialization code, make -MinEmacs runnable on older Emacs versions, etc. - -1. The =~/.minemacs.d/early-config.el= file is loaded at the end of MinEmacs' - =early-init.el=. You can use it to set up some early stuff like tweaking the - UI, overwrite the variables set by MinEmacs, and so on. -2. The =~/.minemacs.d/init-tweaks.el= file is loaded at an early stage of the - =init.el= file. You can use it to do some useful stuff before MinEmacs starts - to customize packages and load modules. This can be useful for porting - MinEmacs to an older Emacs version by providing an implementation of new - functions MinEmacs uses. See the [[file:init.el][init.el]] for more information. - -*** Environment variables -You can customize MinEmacs' behavior via some environment variables. - -- =MINEMACS_DIR= or =MINEMACSDIR=: Path for MinEmacs user configuration directory, - if not set, =~/.minemacs.d/= is used. -- =MINEMACS_MSG_LEVEL=: Change message log level, from 1 (only errors) to 4 (all - messages). -- =MINEMACS_VERBOSE=: Be more verbose (useful for debugging). -- =MINEMACS_DEBUG=: Enable debugging at startup. -- =MINEMACS_ALPHA=: Set frame =background-alpha= to percentage (value from 0 to - 100). -- =MINEMACS_NOT_LAZY=: Load lazy packages immediately after loading Emacs. -- =MINEMACS_IGNORE_VERSION_CHECK=: Do not perform version check in =init.el=, this - can be useful if you use =~/.minemacs.d/init-tweaks.el= to implement the - functionalities used by MinEmacs and missing from your Emacs version. -- =MINEMACS_IGNORE_CONFIG_EL=, =MINEMACS_IGNORE_MODULES_EL=, - =MINEMACS_IGNORE_EARLY_CONFIG_EL= and =MINEMACS_IGNORE_INIT_TWEAKS_EL=: Ignore - loading, respectively, the user configuration files =~/.minemacs.d/config.el=, - =~/.minemacs.d/modules.el=, =~/.minemacs.d/early-config.el= et - =~/.minemacs.d/init-tweaks.el=. -- =MINEMACS_IGNORE_USER_CONFIG=: Ignore loading all user configuration files - (present in =~/.minemacs.d=, or directory pointed by =$MINEMACSDIR=). - -** Troubleshooting -If you experienced an issue with MinEmacs, you can check the [[file:FAQ.org][FAQ]], check [[https://github.com/abougouffa/minemacs/issues][open -issues or open a new one]].