Crafted Emacs is an attempt to simplify creating a configuration for Emacs. It is not intended to provide all possible configuration for every eventuality. We do envision it being a nice baseline for users who want to create their own Emacs configuration. As a user develops their skill with Emacs Lisp and configuring Emacs in general, we anticipate such a person may end up rewriting their configuration to the point they are no longer using Crafted Emacs. This is an exciting possibility to us, and a journey worth taking!
It is our opinion your configuration is, well, yours! We expect you to own your configuration, but maybe we can help get you started. In the space of "starter kits" for Emacs, we really take to heart the word "starter", in the sense we help you start your configuration. We aren't the kitchen sink and we don't provide every possible configuration. That's your job. It's YOUR configuration.
** Goals :properties: :custom_id: goals :end:
** Principles :PROPERTIES: :custom_id: principles :END:
*** Minimal, modular configuration
The core configuration only sets up Emacs to have a cleaner presentation with sensible defaults. It is up to the user to decide which ~crafted-*~ modules to load.
Configuration modules depend on other modules and the base configuration as little as possible.
The implication is that someone should be able to install or copy code from a ~crafted-*~ module into their own configuration /without/ using Crafted Emacs.
*** Prioritize built-in Emacs functionality
Where possible, we leverage built-in Emacs functionality instead of external packages. When we choose external packages, we prefer those which are layered on top of existing, built-in, functionality. For example:
*** Can be integrated with a Guix configuration
It should be possible to customize aspects of the Crafted Emacs configuration inside of a Guix Home configuration so that things like font sizes, themes, etc can be system-specific.
It can also use packages installed via the Guix package manager instead of ~package.el~.
*** Helps you learn Emacs Lisp
Instead of providing a higher-level configuration system out of the box like other Emacs configurations, we follow standard Emacs Lisp patterns so that you can learn by reading the configuration. We do our best to provide clear comments where necessary to help the reader understand our choices and how the code works.
*** Reversible
We recognize not everyone will agree with our decisions, so each customization should be easily reversible in the users configuration file.
Generally, getting started with Crafted Emacs is as simple as cloning the project from GitHub:
git clone https://github.com/SystemCrafters/crafted-emacs
After cloning the Crafted Emacs repo, to use the modules, you need to add the following to your configuration:
;; This assumes you cloned Crafted Emacs in you home directory, if you ;; didn't, make sure to update the path to correctly reflect the ;; location on your system. (load "~/crafted-emacs/modules/crafted-init-config")
This adds the ~crafted-emacs/modules~ folder to the ~load-path~. If you need to have packages installed, look for modules ending with ~-packages.el~, if you only want the configuration, then the modules ending with ~-config.el~ will be what you want.
For more detailed examples, see the [[file:docs/getting-started-guide.org][Getting Started Guide]]. There are also examples in the ~crafted-emacs/examples~ folder.
This is a community-run modular Emacs configuration, for which we appreciate feedback in the form of issues and pull requests. Feel free to open an issue prior to opening a pull request if you're not certain your idea is in the spirit of the [[#principles][Principles]].
If you enjoy crafting your computing experience, join the [[https://systemcrafters.net/][SystemCrafters]] community!
** Contributing Tips for Elisp
** Contributing Tips for Issues
We welcome your questions and ideas, please open an issue if you have one!
Pease keep in mind, we only support released versions of Emacs. Development versions of Emacs may have incompatibilities, defects or incomplete features. Trying to support development versions of Emacs is like shooting at a moving target; not impossible, but a lot more difficult than may be expected. Applying changes to Crafted Emacs to accomodate development versions of Emacs may break things for those who use a released version.
Troubleshooting :PROPERTIES: :custom_id: troubleshooting :END:
Some tips when things don't seem to work right.
** A package (suddenly?) fails to work
This scenario happened frequently when upgrading to Emacs 28. It also may occur in other scenarios as well. Usually, you will see some message indicating some symbol is void or some function or command does not exist. More often than not, the package maintainer is using a feature from another package which has not yet been released. The new feature is available in the development version of the package however.
Here are some example issues where things went wrong:
[[https://github.com/SystemCrafters/crafted-emacs/issues/126][Wrong number of arguments error]]
[[https://github.com/SystemCrafters/crafted-emacs/issues/132][Example config doesn't start]]
[[https://github.com/SystemCrafters/crafted-emacs/issues/140][there are some bugs in package "helpful"]]
Here are some strategies:
Check the code on the package source control page (ie GitHub, GitLab or whatever), and make sure the missing code is present on the ~master~ branch.
Look at the code associated with the released version (you need to look at the most recent tag for this). If the code is missing there, ask the maintainer for a new release. Often, there are years between releases of Emacs packages, but that depends completely on the package maintainer. Some of them release more frequently, others only on request.
Once you have followed the steps above, you can choose to take one of these actions in your configuration:
Option 1
Option 2
Edit your ~early-init.el~ file, if you are using one. If you aren't using one, add the code mentioned next before any calls to ~package-initialize~ or ~package-install-selected-packages~.
Add a line similar to this to pin the offending package to MELPA (make sure to replace /package-name/ with the name of the actual package):
(add-to-list 'package-pinned-packages (cons 'package-name "melpa"))
Use ~M-x package-list-packages~ to display the list of packages.
Find the package in the list, press the letter 'D' and the letter 'X' to uninstall that package.
Restart Emacs, the package should be installed from MELPA thus using the development version of the package instead of the released version.
Regardless, always feel free to open an issue here and we can help you out. Please be as complete as possible in your description of the problem. Include any stack traces Emacs provides (ie start Emacs with: ~emacs --debug-init~), mention the version number of the package you are installing, and anything you might have tried but which didn't work for you.
This code is licensed under the MIT License. Why? So you can copy the code from this configuration!