parent
03ccb174db
commit
45bf3825dd
1 changed files with 405 additions and 338 deletions
743
README.md
743
README.md
|
@ -1,10 +1,12 @@
|
|||
<a name="top" id="fork-destination-box"></a>
|
||||
<a href="https://develop.spacemacs.org"><img src="https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg" alt="Made with Spacemacs"><a href="https://www.gnu.org/licenses/gpl-3.0.en.html"><img src="https://github.com/syl20bnr/spacemacs/blob/655e2886d88f79f4da01d607d29342e7447cad65/assets/gplv3.png" alt="GPLv3 Software" align="right" width="70" height="28"></a></a><a href="https://www.twitter.com/spacemacs"><img src="https://i.imgur.com/tXSoThF.png" alt="Twitter" align="right"></a><br>
|
||||
- - -
|
||||
<a href="https://develop.spacemacs.org"><img src="assets/spacemacs-badge.svg" alt="Made with Spacemacs" height="20"></a>
|
||||
<a href="https://www.gnu.org/licenses/gpl-3.0.en.html"><img src="assets/gplv3.png" alt="GPLv3 Software" align="right" height="20"></a>
|
||||
<a href="https://www.twitter.com/spacemacs"><img src="https://i.imgur.com/tXSoThF.png" alt="Twitter" align="right" height="20"></a>
|
||||
|
||||
<!-- logo and links -->
|
||||
<p align="center"><img src="/doc/img/title2.png" alt="Spacemacs"/></p>
|
||||
<p align="center">
|
||||
<span align="center">
|
||||
<p><img src="doc/img/title2.png" alt="Spacemacs"/></p>
|
||||
<p>
|
||||
<b><a href="https://develop.spacemacs.org/doc/DOCUMENTATION#core-pillars">philosophy</a></b>
|
||||
|
|
||||
<b><a href="https://develop.spacemacs.org/doc/DOCUMENTATION#who-can-benefit-from-this">for whom?</a></b>
|
||||
|
@ -20,80 +22,45 @@
|
|||
<b><a href="https://develop.spacemacs.org/doc/FAQ">FAQ</a></b>
|
||||
</p>
|
||||
|
||||
- - -
|
||||
|
||||
<p align="center">
|
||||
<!-- badges -->
|
||||
<p>
|
||||
<a href="https://gitter.im/syl20bnr/spacemacs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/Join Chat.svg" alt="Gitter"></a>
|
||||
<a href="https://discord.gg/p4MddFu6Ag"><img src="https://img.shields.io/badge/chat-on%20discord-7289da.svg" alt="Discord"></a>
|
||||
<a href="https://github.com/syl20bnr/spacemacs/actions/workflows/elisp_test.yml"><img src="https://github.com/syl20bnr/spacemacs/actions/workflows/elisp_test.yml/badge.svg?branch=develop"></a>
|
||||
<a href="https://github.com/syl20bnr/spacemacs/actions/workflows/elisp_test.yml"><img src="https://github.com/syl20bnr/spacemacs/actions/workflows/elisp_test.yml/badge.svg?branch=develop" alt="elisp state"></a>
|
||||
<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESFVNPKP4Y742"><img src="https://img.shields.io/badge/Paypal-Donate-blue.svg" alt="Donate"></a>
|
||||
<a href="https://shop.spreadshirt.com/spacemacs-shop"><img src="https://img.shields.io/badge/Shop-T--Shirts-blue.svg" alt="Donate"></a>
|
||||
<a href="https://shop.spreadshirt.com/spacemacs-shop"><img src="https://img.shields.io/badge/Shop-T--Shirts-blue.svg" alt="Merchandise"></a>
|
||||
<a href="https://www.slant.co/topics/12/~what-are-the-best-programming-text-editors"><img src="https://img.shields.io/badge/Slant-Recommend-ff69b4.svg" alt="Recommend it"></a>
|
||||
</p>
|
||||
</span>
|
||||
|
||||
- - -
|
||||
|
||||
**Quick Start**
|
||||
|
||||
**Quick Install**
|
||||
If you *don't* have an existing Emacs setup and want to run Spacemacs as your
|
||||
configuration, and if you have all [prerequisites](#prerequisites) installed,
|
||||
you can install Spacemacs with one line:
|
||||
|
||||
This assumes you don't have an existing Emacs setup and want to run Spacemacs as
|
||||
your config. If you do have one, look at the [full installation
|
||||
instructions](#install) for other options.
|
||||
|
||||
```shell
|
||||
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
|
||||
```
|
||||
|
||||
* Windows Command Prompt:
|
||||
```
|
||||
git clone https://github.com/syl20bnr/spacemacs %appdata%/.emacs.d
|
||||
* shell:
|
||||
```sh
|
||||
git clone https://github.com/syl20bnr/spacemacs $HOME/.emacs.d
|
||||
```
|
||||
|
||||
* Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
git clone https://github.com/syl20bnr/spacemacs $env:appdata/.emacs.d
|
||||
git clone https://github.com/syl20bnr/spacemacs $HOME/.emacs.d
|
||||
```
|
||||
|
||||
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
|
||||
**Table of Contents**
|
||||
If `HOME` is not set in environment or in registry:
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Features](#features)
|
||||
- [Documentation](#documentation)
|
||||
- [Getting Help](#getting-help)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Emacs](#emacs)
|
||||
- [Linux distros](#linux-distros)
|
||||
- [macOS](#macos)
|
||||
- [Install emacs](#install-emacs)
|
||||
- [Using emacs-plus](#using-emacs-plus)
|
||||
- [Using emacs-mac](#using-emacs-mac)
|
||||
- [Using cask](#using-cask)
|
||||
- [Other ways](#other-ways)
|
||||
- [Install Source Code Pro font](#install-source-code-pro-font)
|
||||
- [Install Spacemacs](#install-spacemacs)
|
||||
- [Windows](#windows)
|
||||
- [Install Spacemacs in Windows](#install-spacemacs-in-windows)
|
||||
- [Notes](#notes)
|
||||
- [Install](#install)
|
||||
- [Default installation](#default-installation)
|
||||
- [Alternative installations](#alternative-installations)
|
||||
- [Modify HOME environment variable](#modify-home-environment-variable)
|
||||
- [Modify spacemacs-start-directory variable](#modify-spacemacs-start-directory-variable)
|
||||
- [Spacemacs logo](#spacemacs-logo)
|
||||
- [Update](#update)
|
||||
- [Rolling update (on develop)](#rolling-update-on-develop)
|
||||
- [Automatic update (on master branch)](#automatic-update-on-master-branch)
|
||||
- [Manual update (on master branch)](#manual-update-on-master-branch)
|
||||
- [Revert to a specific version (on master branch)](#revert-to-a-specific-version-on-master-branch)
|
||||
- [Quotes](#quotes)
|
||||
- [Contributions](#contributions)
|
||||
- [Communities](#communities)
|
||||
- [Spacemacs Everywhere](#spacemacs-everywhere)
|
||||
- [License](#license)
|
||||
- [Supporting Spacemacs](#supporting-spacemacs)
|
||||
```powershell
|
||||
git clone https://github.com/syl20bnr/spacemacs $env:APPDATA/.emacs.d
|
||||
```
|
||||
|
||||
<!-- markdown-toc end -->
|
||||
If you do have an existing Emacs configuration, look at the [full installation
|
||||
instructions](#install) for other options.
|
||||
|
||||
# Introduction
|
||||
Spacemacs is a new way of experiencing Emacs -- it's a sophisticated and
|
||||
|
@ -122,167 +89,372 @@ mode-line.
|
|||
<kbd>SPC b</kbd> for all the buffer commands or <kbd>SPC p</kbd> for the project
|
||||
commands.
|
||||
- **Batteries included:** discover hundreds of ready-to-use packages nicely
|
||||
organized in configuration layers following a set of
|
||||
[conventions][CONVENTIONS.org].
|
||||
organized in configuration layers following a set of [conventions
|
||||
][CONVENTIONS.org].
|
||||
|
||||
# Documentation
|
||||
Comprehensive documentation is available for each layer by pressing <kbd>SPC h
|
||||
SPC</kbd>.
|
||||
|
||||
You can also check the [general documentation][DOCUMENTATION.org], [quick start
|
||||
guide][QUICK_START.org] and the [FAQ][FAQ.org].
|
||||
You can also check the [general documentation][DOCUMENTATION.org],
|
||||
[quick start guide][QUICK_START.org] and the [FAQ][FAQ.org].
|
||||
|
||||
# Getting Help
|
||||
If you need help, ask your question in the [Gitter Chat][] and a member of the
|
||||
If you need help, ask your questions in the [Gitter Chat][] and a member of the
|
||||
community will help you out.
|
||||
|
||||
If you prefer IRC, connect to the [Gitter Chat IRC server][] and join the
|
||||
`#syl20bnr/spacemacs` channel.
|
||||
|
||||
Last but not least there are a lot of high class tutorials available on YouTube:
|
||||
* Jack of Some's Spacemacs related channel [here](https://www.youtube.com/watch?v=r-BHx7VNX5s&list=PLd_Oyt6lAQ8Rxb0HUnGbRrn6R4Cdt2yoI)
|
||||
* GDQuest's Game Design oriented tutorials to Spacemacs [here](https://www.youtube.com/watch?v=hCNOB5jjtmc&list=PLhqJJNjsQ7KFkMVBunWWzFD8SlH714qm4)
|
||||
* Practicalli's Clojure tutorials based on Spacemacs [here](https://www.youtube.com/watch?v=ZKuQDrQLAnc&list=PLpr9V-R8ZxiCHMl2_dn1Fovcd34Oz45su)
|
||||
* Eivind Fonn's classic Spacemacs ABC [here](https://www.youtube.com/watch?v=ZFV5EqpZ6_s&list=PLrJ2YN5y27KLhd3yNs2dR8_inqtEiEweE)
|
||||
* Jack of Some's [Spacemacs tutorial videos][jack-of-some].
|
||||
* GDQuest's [Game Design oriented tutorials ][gdquest] to Spacemacs.
|
||||
* Practicalli's [Clojure tutorials based on Spacemacs][practicalli].
|
||||
* Eivind Fonn's classic [Spacemacs ABC][eivind-fonn].
|
||||
|
||||
# Prerequisites
|
||||
Spacemacs is an extension of a popular text editor called Emacs. Thus you need
|
||||
to first install base Emacs and then download the Spacemacs extension files with
|
||||
Git.
|
||||
|
||||
## Emacs
|
||||
Spacemacs requires Emacs 27.1 or above. The development version of Emacs is not
|
||||
*officially* supported, but it should nevertheless be expected to work.
|
||||
1. A package manager if the OS doesn't have one already.
|
||||
|
||||
Some modes require third-party tools that you'll have to install via your
|
||||
favorite package manager.
|
||||
2. Spacemacs is an extension of a popular text editor called [Emacs][GNU Emacs].
|
||||
So you'll need Emacs installed first.
|
||||
|
||||
### Linux distros
|
||||
Install the `emacs` package with your linux distributions package manager.
|
||||
Spacemacs requires Emacs 27.1 or above. The development version of Emacs is
|
||||
not *officially* supported, but it should nevertheless be expected to work.
|
||||
|
||||
Do not install the `xemacs` package. It's not supported by Spacemacs. XEmacs is
|
||||
an old fork of Emacs. The X in its name is unrelated to X11.
|
||||
3. [git][Git] is required to download and update Spacemacs.
|
||||
|
||||
Emacs has graphical support.
|
||||
4. Tar, either [GNU Tar][] or [BSD Tar][], is required to install and update
|
||||
Emacs packages used by Spacemacs.
|
||||
|
||||
**Note:** Some linux distributions support only Emacs versions older than 27.1.
|
||||
In this case you should [build from source][build_source] instead.
|
||||
5. *(Optional)* The default font used by Spacemacs is [Source Code Pro][]. You
|
||||
may customize your own font settings and choose another font. If you want to
|
||||
use this default font, it must be installed.
|
||||
|
||||
Spacemacs also uses fallback fonts to ensure certain Unicode symbols it uses
|
||||
symbols appear correctly. The fonts used are determined by the OS:
|
||||
|
||||
- Linux: [Nanum Gothic][]
|
||||
- macOS: [Arial Unicode MS][]
|
||||
- Windows: [MS Gothic][] and [Lucida Sans Unicode][]
|
||||
|
||||
If the mode-line doesn't look similar to the [picture at the top of this
|
||||
page](#introduction), make sure you have the correct fallback font installed.
|
||||
|
||||
6. *(Optional)* Various commands in Spacemacs needs one of the following line
|
||||
searching program:
|
||||
|
||||
- [ripgrep (rg)][ripgrep]
|
||||
- [The silver searcher (ag)][ag]
|
||||
- [The platinum searcher (pt)][pt]
|
||||
- [ack][]
|
||||
- [GNU Grep][] or [BSD Grep][]
|
||||
|
||||
Grep is very slow but it's widely available on most systems and is used as an
|
||||
fallback option.
|
||||
|
||||
We strongly recommend [ripgrep][] over other line searching programs, for its
|
||||
blazing fast speed. The following subsections helps you to install it.
|
||||
|
||||
### Linux
|
||||
|
||||
1. Most Linux distribution ships a package manager already and if this is the
|
||||
case you are all set for this step.
|
||||
|
||||
If it doesn't, you may need to build the softwares mentioned below from their
|
||||
sources.
|
||||
|
||||
2. In most distributions, Emacs is installed via an `emacs` package from the
|
||||
package manager.
|
||||
|
||||
**N.B.** DO not install [XEmacs][] because it's not supported by Spacemacs.
|
||||
XEmacs is an old fork of Emacs with various [subtle
|
||||
differences][Emacs And XEmacs].
|
||||
|
||||
**N.B.** Some Linux distributions support only Emacs versions older than
|
||||
27.1. In this case you should
|
||||
[build it from source][Build Emacs from Source] instead.
|
||||
|
||||
3. Very likely Git is already installed on your system. Otherwise, you should
|
||||
be able to install `git` from your system's package manager.
|
||||
|
||||
4. Very likely Tar is already installed on your system. Otherwise, you should
|
||||
be able to install `tar` from your system's package manager.
|
||||
|
||||
5. *(Optional)* If Nerd Fonts and Nanum Gothic are available from your
|
||||
distribution's package manager, you should install it there.
|
||||
|
||||
Otherwise, the generic way to install it is:
|
||||
|
||||
1. Download the latest pre-built `TTF` font from
|
||||
<https://github.com/adobe-fonts/source-code-pro/releases/latest> and
|
||||
<https://fonts.google.com/specimen/Nanum+Gothic>.
|
||||
|
||||
2. Extract the archive and move the font files to `~/.fonts`.
|
||||
|
||||
3. Refresh font cache with:
|
||||
|
||||
```sh
|
||||
fc-cache -fv
|
||||
```
|
||||
|
||||
6. *(Optional)* If your distribution is listed [here][ripgrep-installation],
|
||||
follow the instructions. Otherwise, you can download its pre-built binary or
|
||||
build it from source.
|
||||
|
||||
### macOS
|
||||
|
||||
#### Install emacs
|
||||
1. The most popular package manager on macOS is [Homebrew][], to install it:
|
||||
|
||||
##### Using emacs-plus
|
||||
```sh
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
```
|
||||
|
||||
```shell
|
||||
brew tap d12frosted/emacs-plus
|
||||
2. Several options exist for installing Emacs on macOS:
|
||||
|
||||
# to install Emacs 27
|
||||
brew install emacs-plus@27 --with-spacemacs-icon
|
||||
# or to install Emacs 28
|
||||
brew install emacs-plus@28 --with-spacemacs-icon
|
||||
1. [Emacs Plus][] features [additional functionalities][Emacs Plus features]
|
||||
over base Emacs.
|
||||
|
||||
brew link emacs-plus
|
||||
```
|
||||
```sh
|
||||
brew tap d12frosted/emacs-plus
|
||||
|
||||
##### Using emacs-mac
|
||||
# install latest stable release, with Spacemacs icon and native compilation
|
||||
brew install emacs-plus --with-spacemacs-icon --with-native-comp
|
||||
```
|
||||
|
||||
```shell
|
||||
brew tap railwaycat/emacsmacport
|
||||
brew install emacs-mac
|
||||
brew link emacs-mac
|
||||
```
|
||||
2. [Emacs Mac Port][] adds native GUI support to Emacs 28. And the full list
|
||||
of features is available [here][Emacs Mac Port features].
|
||||
|
||||
##### Using cask
|
||||
```sh
|
||||
brew tap railwaycat/emacsmacport
|
||||
brew install emacs-mac
|
||||
```
|
||||
|
||||
Homebrew now recommends to use the cask version with the following message:
|
||||
"Please try the Cask for a better-supported Cocoa version". To install the cask
|
||||
version:
|
||||
3. [Emacs for Mac OS X][] is the binary build of GNU Emacs, *without* any
|
||||
extra feature.
|
||||
|
||||
```shell
|
||||
brew install --cask emacs
|
||||
```
|
||||
```sh
|
||||
brew install --cask emacs
|
||||
```
|
||||
|
||||
This installs a pre-built package from https://emacsformacosx.com/
|
||||
3. To install `git`:
|
||||
|
||||
##### Other ways
|
||||
```sh
|
||||
brew install git
|
||||
```
|
||||
|
||||
If you're not comfortable with the ways mentioned above, then
|
||||
[EmacsWiki][emacs-for-macos] lists down a few ways to install Emacs for macOS.
|
||||
4. macOS ships with [BSD Tar][] so you don't need to install it.
|
||||
|
||||
#### Install Source Code Pro font
|
||||
5. *(Optional)* To install Source Code Pro Font:
|
||||
|
||||
Once Emacs is installed, run the following commands in the terminal to install
|
||||
the default Source Code Pro font:
|
||||
```sh
|
||||
brew tap homebrew/cask-fonts
|
||||
brew install --cask font-source-code-pro
|
||||
```
|
||||
|
||||
```shell
|
||||
brew tap homebrew/cask-fonts
|
||||
brew install --cask font-source-code-pro
|
||||
```
|
||||
Arial Unicode MS is shipped with macOS v10.5 and later so you don't need to
|
||||
install it manually.
|
||||
|
||||
#### Install Spacemacs
|
||||
6. *(Optional)* You can install `ripgrep` via `Homebrew`:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
It's also recommended to add the [osx layer][] to your [dotfile][] after
|
||||
completing the Spacemacs [install process](#install). Instructions on how to do
|
||||
so are available in the documentation for the [osx layer][].
|
||||
|
||||
Depending on the installed version of GnuTLS, securely installing emacs packages
|
||||
may fail. In this case it is possible to install using `emacs --insecure`.
|
||||
However, be aware that this means your packages will be transferred using http,
|
||||
use at your own risk.
|
||||
|
||||
You may also have some issues when searching for your projects. It is
|
||||
recommended to install the GNU [ripgrep][ripgrep-homebrew] through homebrew:
|
||||
|
||||
```shell
|
||||
brew install ripgrep
|
||||
```
|
||||
```sh
|
||||
brew install ripgrep
|
||||
```
|
||||
|
||||
### Windows
|
||||
Download the official 64-bit (x86_64) stable builds from the [GNU
|
||||
FTP][emacs-for-windows].
|
||||
|
||||
You'll also need `gzip` and put it in your path. Download it from the [GNUWin32
|
||||
project page][gzip-for-windows]
|
||||
1. We recommend [Scoop][] as the package manager for Windows users. You can
|
||||
install it via PowerShell:
|
||||
|
||||
#### Install Spacemacs in Windows
|
||||
By default, Emacs looks for the `.emacs.d` directory in:
|
||||
`C:\Users\<username>\AppData\Roaming`
|
||||
```powershell
|
||||
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # Optional: Needed to run a remote script the first time
|
||||
irm get.scoop.sh | iex
|
||||
```
|
||||
|
||||
* Clone Spacemacs to the Roaming directory:
|
||||
* Windows Command Prompt:
|
||||
```
|
||||
git clone https://github.com/syl20bnr/spacemacs %appdata%/.emacs.d
|
||||
```
|
||||
2. Emacs can be installed in PowerShell:
|
||||
|
||||
```powershell
|
||||
scoop bucket add extras
|
||||
scoop install emacs
|
||||
```
|
||||
|
||||
3. To install `git` in PowerShell:
|
||||
|
||||
```powershell
|
||||
scoop bucket add main
|
||||
scoop install git
|
||||
```
|
||||
|
||||
4. Windows 10 build 17063 and later ships with [BSD Tar][] and you won't need to
|
||||
install it manually.
|
||||
|
||||
If you're running an earlier version of Windows, Tar can be installed in
|
||||
PowerShell:
|
||||
|
||||
```powershell
|
||||
scoop bucket add main
|
||||
scoop install tar
|
||||
```
|
||||
|
||||
5. To install Source Code Pro Font in PowerShell:
|
||||
|
||||
```powershell
|
||||
scoop bucket add KnotUntied_scoop-fonts https://github.com/KnotUntied/scoop-fonts
|
||||
scoop install sourcecodepro
|
||||
```
|
||||
|
||||
MS Gothic and Lucida Sans Unicode are shipped with Windows 2003 and later so
|
||||
you don't need to install it manually.
|
||||
|
||||
6. *(Optional)* You can install `ripgrep` in PowerShell:
|
||||
|
||||
```powershell
|
||||
scoop bucket add main
|
||||
scoop install ripgrep
|
||||
```
|
||||
|
||||
# Install
|
||||
|
||||
## Default Install
|
||||
|
||||
1. The default installation downloads Spacemacs to the `.emacs.d` directory in
|
||||
your `HOME` directory.
|
||||
|
||||
But in the case of Windows, `HOME` is not set out-of-box. We recommend you to
|
||||
set it as an environment variable, with the same value as environment
|
||||
variable `HOMEPATH`, which usually looks like `C:\Users\<username>`.
|
||||
|
||||
2. Since Spacemacs will now be downloaded at `$HOME/.emacs.d`, if it already
|
||||
exists it'll be overridden.
|
||||
|
||||
Also, if you have either `$HOME/.emacs.el` or `$HOME/.emacs`, they will
|
||||
appear before Spacemacs in Emacs's initialization steps. Thus they must be
|
||||
renamed in order for Spacemacs to load correctly.
|
||||
|
||||
To backup/rename the aforementioned files/directory, in shell:
|
||||
|
||||
```sh
|
||||
[ -d $HOME/.emacs.d ] && mv $HOME/.emacs.d $HOME/.emacs.d.bak
|
||||
[ -f $HOME/.emacs.el ] && mv $HOME/.emacs.el .emacs.el.bak
|
||||
[ -f $HOME/.emacs ] && mv $HOME/.emacs $HOME/.emacs.bak
|
||||
```
|
||||
|
||||
or in PowerShell:
|
||||
|
||||
* Windows PowerShell prompt:
|
||||
```powershell
|
||||
git clone https://github.com/syl20bnr/spacemacs $env:appdata/.emacs.d
|
||||
if( TestPath -Path $HOME/.emacs.d )
|
||||
{
|
||||
Rename-Item $HOME/.emacs.d $HOME/.emacs.d.bak
|
||||
}
|
||||
if( TestPath -Path $HOME/.emacs.el )
|
||||
{
|
||||
Rename-Item $HOME/.emacs.el $HOME/.emacs.el.bak
|
||||
}
|
||||
if( TestPath -Path $HOME/.emacs )
|
||||
{
|
||||
Rename-Item $HOME/.emacs $HOME/.emacs.bak
|
||||
}
|
||||
```
|
||||
|
||||
* Or if a `HOME` environment variable has been configured that points to your
|
||||
user directory: `C:\Users\<username>`
|
||||
3. Now clone this repository with Git. The following work for both shell
|
||||
and PowerShell:
|
||||
|
||||
Clone Spacemacs to the `<username>` directory:
|
||||
* Windows Command Prompt:
|
||||
```
|
||||
git clone https://github.com/syl20bnr/spacemacs %homepath%/.emacs.d
|
||||
```
|
||||
```sh
|
||||
git clone https://github.com/syl20bnr/spacemacs $HOME/.emacs.d
|
||||
```
|
||||
|
||||
* Windows PowerShell prompt:
|
||||
```powershell
|
||||
git clone https://github.com/syl20bnr/spacemacs $home/.emacs.d
|
||||
```
|
||||
In case you have a limited internet connection or limited speed:
|
||||
|
||||
#### Notes
|
||||
```sh
|
||||
git clone --depth 1 https://github.com/syl20bnr/spacemacs ~/.emacs.d
|
||||
```
|
||||
|
||||
* If the following error occurs after starting Emacs:
|
||||
4. Now you can launch Emacs and Spacemacs will be loaded.
|
||||
|
||||
## Alternative Install Location
|
||||
|
||||
To install Spacemacs in a different location, we first need to introduce how
|
||||
Spacemacs is loaded:
|
||||
|
||||
When Emacs is started, it looks for the init file
|
||||
[in a deterministic way][Emacs: Find Init]. The
|
||||
[default installation](#default-install) exploits it by occupying
|
||||
`$HOME/.emacs.d/init.el` and let Emacs use it as its init file.
|
||||
|
||||
In other word, in default installation, Emacs find and load
|
||||
`$HOME/.emacs.d/init.el`, which is then responsible to load other files in
|
||||
`$HOME/.emacs.d`.
|
||||
|
||||
If you want to install Spacemacs to a different location, you need to make
|
||||
sure it's loaded by Emacs in one of its [init file][Emacs: Find Init].
|
||||
|
||||
For example, if you've cloned Spacemacs to `$HOME/spacemacs`, and if you use
|
||||
`$HOME/.emacs.el` as Emacs init file, then the following lines in
|
||||
`$HOME/.emacs.el`:
|
||||
|
||||
```elisp
|
||||
;; set variable `spacemacs-start-directory' to point to your Spacemacs
|
||||
;; installation location, "~" is equivalent to "$HOME"
|
||||
(setq spacemacs-start-directory "~/.emacs.d/spacemacs")
|
||||
;; load Spacemacs's initialization file
|
||||
(load-file (expand-file-name "init.el" spacemacs-start-directory))
|
||||
```
|
||||
|
||||
# First Launch and Configuration
|
||||
|
||||
1. After cloning Spacemacs, the first time when you launch Emacs, Spacemacs will
|
||||
automatically install the essential packages it requires. This step is the
|
||||
bootstrap.
|
||||
|
||||
2. Once the bootstrap packages are installed, Spacemacs checks whether you have
|
||||
an customization file `$HOME/.spacemacs`, known as `dotspacemacs`:
|
||||
|
||||
- If it already exists, Spacemacs loads it as the configuration.
|
||||
- Otherwise, you need to answer a few questions and Spacemacs will generate
|
||||
the `dotspacemacs` file for you.
|
||||
|
||||
If you are new to Emacs and/or Spacemacs, it's fine to just accept the
|
||||
default choices. They can be changed in the `dotspacemacs` file later.
|
||||
|
||||
3. Spacemacs will download and install remaining packages it will require,
|
||||
according to your `dotspacemacs`. When the all the packages have been
|
||||
installed, restart Emacs to complete the installation.
|
||||
|
||||
4. `dotspacemacs` is the configuration file for Spacemacs, it's self
|
||||
explanatory and is written in Emacs Lisp. Read
|
||||
[general documentation][DOCUMENTATION.org] and
|
||||
[quick start guide][QUICK_START.org] for more information.
|
||||
|
||||
5. In case you want to store your `dotspacemacs` at another location, say
|
||||
under `$HOME/.spacemacs.d`:
|
||||
|
||||
- First set the environment variable `SPACEMACSDIR` to `$HOME/.spacemacs.d`.
|
||||
- Move `$HOME/.spacemacs` to `$HOME/.spacemacs.d/init.el`.
|
||||
|
||||
In other word, set `SPACEMACSDIR` to the parent directory of your
|
||||
`dotspacemacs`, and move `dotspacemacs` to the said directory.
|
||||
|
||||
## Spacemacs logo
|
||||
|
||||
For Linux users, create `spacemacs.desktop` in `~/.local/share/applications/`
|
||||
using [this .desktop file][spacemacs-desktop] as a reference. Change the `Name`
|
||||
parameter to `Name=Spacemacs` and the `Icon` parameter to
|
||||
`Icon=/PATH/TO/EMACSD/core/banners/img/spacemacs.png` where `PATH/TO/EMACSD` is
|
||||
the path to your `.emacs.d` directory, by default `~/.emacs.d`.
|
||||
|
||||
For macOS users, you need to [download the .icns version of the
|
||||
logo][icon-repository] and simply [change the logo on the
|
||||
Dock][icon-mac-instructions].
|
||||
|
||||
## Notes
|
||||
|
||||
- Depending on the installed version of GnuTLS, securely installing Emacs
|
||||
packages may fail. It may also fail if you have a bad internet environment.
|
||||
In either case it is possible to install packages using `emacs --insecure`.
|
||||
However be aware that this means your packages will be transferred using HTTP,
|
||||
use at your own risk.
|
||||
|
||||
- (*Windows)* If the following error occurs after starting Emacs:
|
||||
|
||||
```
|
||||
The directory ~/.emacs.d/server is unsafe
|
||||
|
@ -296,146 +468,19 @@ user directory: `C:\Users\<username>`
|
|||
|
||||
Source: [Stack Overflow][so-server-unsafe]
|
||||
|
||||
* For efficient searches, we recommend installing [ripgrep][ripgrep-github].
|
||||
|
||||
* Depending on the installed version of GnuTLS, securely installing emacs
|
||||
packages may fail. In this case it is possible to install using `emacs
|
||||
--insecure`. However be aware that this means your packages will be transferred
|
||||
using http, use at your own risk.
|
||||
|
||||
* The period (dot) before a file or folder name means that it's a hidden file or
|
||||
folder. To show hidden files and folders:
|
||||
- (*Windows*) The period (dot) before a file or folder name means that it's a
|
||||
hidden file or folder. To show hidden files and folders:
|
||||
- Press the Windows key
|
||||
- Type `File explorer options`
|
||||
- Select the `View` tab at the top
|
||||
- Check `Show hidden files, folders and drives`
|
||||
- Click `OK`
|
||||
|
||||
# Install
|
||||
## Default installation
|
||||
1. If you have an existing Emacs configuration, back it up first by running the
|
||||
following code in your terminal:
|
||||
|
||||
```shell
|
||||
cd ~
|
||||
mv .emacs.d .emacs.d.bak
|
||||
mv .emacs .emacs.bak
|
||||
```
|
||||
|
||||
Don't forget to backup and *remove* the `~/.emacs` file. Otherwise Spacemacs
|
||||
**WILL NOT** be able to load. This is because that file will prevent Emacs
|
||||
from loading the proper initialization file.
|
||||
|
||||
2. Clone the repository with [Git][]:
|
||||
|
||||
**Note: Windows users**, see [Windows section](#install-spacemacs-in-windows).
|
||||
|
||||
```shell
|
||||
git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d
|
||||
```
|
||||
|
||||
Or in case you have a limited internet connection or speed,
|
||||
|
||||
```shell
|
||||
git clone --depth 1 https://github.com/syl20bnr/spacemacs ~/.emacs.d
|
||||
```
|
||||
|
||||
3. (Optional) Install the default fonts
|
||||
|
||||
It's recommended to install [Source Code Pro][] by Adobe as the default font.
|
||||
It ensures that, for example, the symbols on the mode-line (bottom bar) looks
|
||||
correct. It's also recommended to use a "Fallback font". These depend on the
|
||||
system:
|
||||
|
||||
- GNU/Linux: *NanumGothic* (package named *fonts-nanum* on Debian, for
|
||||
example)
|
||||
- macOS: *Arial Unicode MS*
|
||||
- Windows: *MS Gothic* or *Lucida Sans Unicode*
|
||||
|
||||
If the mode-line doesn't look similar to the [picture at the top of this
|
||||
page](#introduction), make sure you have the correct fallback font installed.
|
||||
|
||||
If you're running in a terminal, then you'll also need to change the
|
||||
terminal's font settings.
|
||||
|
||||
4. Launch Emacs. Spacemacs will automatically install the packages it requires.
|
||||
|
||||
5. Once the packages are installed, answer the questions in the Dotfile wizard
|
||||
installer. If you are new to Emacs and Spacemacs, then it's fine to just
|
||||
accept the default choices. It's easy to try the other choices later, without
|
||||
having to reinstall Spacemacs. They can be changed in the dotfile
|
||||
`~/.spacemacs`.
|
||||
|
||||
6. After answering the questions, Spacemacs will download and install the
|
||||
remaining packages it will require. When the all the packages have been
|
||||
installed, restart Emacs to complete the installation.
|
||||
|
||||
**Notes:**
|
||||
If you are behind a firewall or similar and you get an error regarding package
|
||||
downloads then you may try to disable the HTTPS protocol by starting Emacs with
|
||||
```shell
|
||||
emacs --insecure
|
||||
```
|
||||
but this should be a last resort because of the security implications.
|
||||
|
||||
You can set the `dotspacemacs-elpa-https` variable to `nil` in your dotfile
|
||||
`~/.spacemacs` but this has the same security implications as the insecure flag.
|
||||
You may also want to clear out your `.emacs.d/elpa` directory before doing this,
|
||||
so that any corrupted packages you may have downloaded will be re-installed.
|
||||
|
||||
`error: Package 'package-build-' is unavailable` may occur due to heavy network
|
||||
taffic. You can fix it by setting the `dotspacemacs-elpa-timeout` variable to
|
||||
`70` in your dotfile.
|
||||
|
||||
`Warning (bytecomp)` and other compilation warnings are perfectly normal. If
|
||||
you're curious, you can find out why these occur [here][compilation-warnings].
|
||||
|
||||
If the mode-line turns red, then be sure to consult the [FAQ][FAQ.org].
|
||||
|
||||
## Alternative installations
|
||||
Currently, there are two supported locations for you to place your Spacemacs
|
||||
configuration files.
|
||||
|
||||
### Modify HOME environment variable
|
||||
This solution is ideal for quickly trying Spacemacs without compromising your
|
||||
existing configuration. Clone Spacemacs outside the Emacs dotdirectory
|
||||
`~/.emacs.d` and modify the HOME environment variable.
|
||||
|
||||
```shell
|
||||
mkdir ~/spacemacs
|
||||
git clone https://github.com/syl20bnr/spacemacs.git ~/spacemacs/.emacs.d
|
||||
HOME=~/spacemacs emacs
|
||||
```
|
||||
|
||||
**Note**: If you're using the Fish shell, then you'll need to modify the last
|
||||
command to: `env HOME=$HOME/spacemacs emacs`
|
||||
|
||||
### Modify spacemacs-start-directory variable
|
||||
This solution is better suited to "embed" Spacemacs into your own configuration.
|
||||
If you've cloned Spacemacs into `~/.emacs.d/spacemacs/`, then drop the following
|
||||
lines in the `~/.emacs.d/init.el` file:
|
||||
|
||||
```elisp
|
||||
(setq spacemacs-start-directory "~/.emacs.d/spacemacs/")
|
||||
(load-file (concat spacemacs-start-directory "init.el"))
|
||||
```
|
||||
|
||||
## Spacemacs logo
|
||||
For Linux users, create `spacemacs.desktop` in `~/.local/share/applications/`
|
||||
using [this .desktop file][spacemacs-desktop] as a reference. Change the `Name`
|
||||
parameter to `Name=Spacemacs` and the `Icon` parameter to
|
||||
`Icon=/PATH/TO/EMACSD/core/banners/img/spacemacs.png` where `PATH/TO/EMACSD` is
|
||||
the path to your `.emacs.d` directory, usually `~/.emacs.d` or
|
||||
`~/.config/emacs`.
|
||||
|
||||
For macOS users, you need to [download the .icns version of the
|
||||
logo][icon-repository] and simply [change the logo on the
|
||||
Dock][icon-mac-instructions].
|
||||
|
||||
# Update
|
||||
|
||||
Spacemacs supports two different update schemes, the default is a rolling update
|
||||
scheme based on the latest version of packages available. This version can be
|
||||
found on the `develop` branch and is updated by a simple git pull.
|
||||
found on the `develop` branch and is updated by a simple `git pull`.
|
||||
|
||||
The second method is deprecated. It was a fixed version scheme which was based
|
||||
on a stable set of packages. The latest fixed version can be found on the
|
||||
|
@ -446,7 +491,7 @@ be very old.
|
|||
## Rolling update (on develop)
|
||||
1. Close Emacs and update the git repository:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
git pull --rebase
|
||||
```
|
||||
|
||||
|
@ -468,16 +513,16 @@ Remove the `<` and `>` angle brackets when you're typing the lines below into
|
|||
your shell. Make sure to also replace the text: "tag version which you are
|
||||
updating to" with a tagged version. This page lists the [latest tags][]
|
||||
|
||||
```shell
|
||||
```sh
|
||||
git fetch
|
||||
git reset --hard <tag version which you are updating to>
|
||||
```
|
||||
|
||||
## Revert to a specific version (on master branch)
|
||||
To revert to a specific version, just checkout the corresponding branch. For
|
||||
instance, the following command reverts Spacemacs to version `0.200`:
|
||||
## Revert to a specific release version (on master branch)
|
||||
To revert to a specific release version, just checkout the corresponding branch.
|
||||
For instance, the following command reverts Spacemacs to version `0.200`:
|
||||
|
||||
```shell
|
||||
```sh
|
||||
git checkout origin/release-0.200
|
||||
```
|
||||
|
||||
|
@ -506,9 +551,9 @@ Before contributing, be sure to consult the [contribution
|
|||
guidelines][CONTRIBUTING.org] and [conventions][CONVENTIONS.org].
|
||||
|
||||
# Communities
|
||||
- [Gitter Chat]
|
||||
- [Stack Exchange]
|
||||
- [Reddit]
|
||||
- [Gitter Chat][]
|
||||
- [Stack Exchange][]
|
||||
- [Reddit][]
|
||||
|
||||
# Spacemacs Everywhere
|
||||
|
||||
|
@ -546,8 +591,8 @@ If you want to show your support financially, then you can contribute to
|
|||
[Bountysource][], or buy a drink for the maintainer by clicking on the [Paypal
|
||||
badge](#top).
|
||||
|
||||
If you used spacemacs in a project, and you want to show that fact, you can use
|
||||
the spacemacs badge: [![Built with
|
||||
If you used Spacemacs in a project, and you want to show that fact, you can use
|
||||
the Spacemacs badge: [![Built with
|
||||
Spacemacs](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg)](https://develop.spacemacs.org)
|
||||
|
||||
- For Markdown:
|
||||
|
@ -570,41 +615,63 @@ Spacemacs](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c208270
|
|||
|
||||
Thank you!
|
||||
|
||||
[Twitter]: https://i.imgur.com/tXSoThF.png
|
||||
[CONTRIBUTING.org]: CONTRIBUTING.org
|
||||
[CONVENTIONS.org]: https://develop.spacemacs.org/doc/CONVENTIONS
|
||||
[DOCUMENTATION.org]: https://develop.spacemacs.org/doc/DOCUMENTATION
|
||||
[QUICK_START.org]: https://develop.spacemacs.org/doc/QUICK_START
|
||||
[FAQ.org]: https://develop.spacemacs.org/doc/FAQ
|
||||
[VIMUSERS.org]: https://develop.spacemacs.org/doc/VIMUSERS
|
||||
[dotfile]: https://develop.spacemacs.org/doc/DOCUMENTATION#dotfile-configuration
|
||||
[osx layer]: https://develop.spacemacs.org/layers/+os/osx/README.html
|
||||
[CONVENTIONS.org]: doc/CONVENTIONS.org
|
||||
[DOCUMENTATION.org]: doc/DOCUMENTATION.org
|
||||
[FAQ.org]: doc/FAQ.org
|
||||
[QUICK_START.org]: doc/QUICK_START.org
|
||||
|
||||
[Gitter Chat]: https://gitter.im/syl20bnr/spacemacs
|
||||
[Gitter Chat IRC server]: https://irc.gitter.im/
|
||||
[Homebrew]: https://brew.sh
|
||||
[emacs-plus]: https://github.com/d12frosted/homebrew-emacs-plus
|
||||
[emacs-for-macos]: https://www.emacswiki.org/emacs/EmacsForMacOS#toc12
|
||||
[powerline documentation]: https://develop.spacemacs.org/doc/DOCUMENTATION.html#powerline-separators
|
||||
[emacs-for-windows]: https://ftp.gnu.org/gnu/emacs/windows/
|
||||
[gzip-for-windows]: http://gnuwin32.sourceforge.net/packages/gzip.htm
|
||||
[ripgrep-github]: https://github.com/BurntSushi/ripgrep
|
||||
[so-server-unsafe]: https://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start
|
||||
[Spacemacs logo]: https://github.com/nashamri/spacemacs-logo
|
||||
[Nasser Alshammari]: https://github.com/nashamri
|
||||
[compilation-warnings]: https://github.com/quelpa/quelpa/issues/90#issuecomment-137982713
|
||||
[cpaulik-unity-icon]: http://splendidabacus.com/posts/2015/03/spacemacs-unity-icon/
|
||||
[icon-mac-instructions]: https://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/
|
||||
[latest tags]: https://github.com/syl20bnr/spacemacs/tags
|
||||
[icon-repository]: https://github.com/nashamri/spacemacs-logo
|
||||
[Stack Exchange]: https://emacs.stackexchange.com/questions/tagged/spacemacs
|
||||
[Reddit]: https://www.reddit.com/r/spacemacs
|
||||
[jack-of-some]: https://www.youtube.com/watch?v=r-BHx7VNX5s&list=PLd_Oyt6lAQ8Rxb0HUnGbRrn6R4Cdt2yoI
|
||||
[gdquest]: https://www.youtube.com/watch?v=hCNOB5jjtmc&list=PLhqJJNjsQ7KFkMVBunWWzFD8SlH714qm4
|
||||
[practicalli]: https://www.youtube.com/watch?v=jMJ58Gcc1RI&list=PLpr9V-R8ZxiCHMl2_dn1Fovcd34Oz45su
|
||||
[eivind-fonn]: https://www.youtube.com/watch?v=ZFV5EqpZ6_s&list=PLrJ2YN5y27KLhd3yNs2dR8_inqtEiEweE
|
||||
|
||||
[GNU Emacs]: https://www.gnu.org/software/emacs/
|
||||
[XEmacs]: https://www.xemacs.org
|
||||
[Emacs And XEmacs]: https://www.emacswiki.org/emacs/EmacsAndXEmacs
|
||||
[Build Emacs from Source]: https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html
|
||||
[Emacs: Find Init]: https://www.gnu.org/software/emacs/manual/html_node/emacs/Find-Init.html
|
||||
[Emacs Plus]: https://github.com/d12frosted/homebrew-emacs-plus
|
||||
[Emacs Plus features]: https://github.com/d12frosted/homebrew-emacs-plus#features-explained
|
||||
[Emacs Mac Port]: https://github.com/railwaycat/homebrew-emacsmacport
|
||||
[Emacs Mac Port features]: https://bitbucket.org/mituharu/emacs-mac/src/master/README-mac
|
||||
[Emacs for Mac OS X]: https://emacsformacosx.com/
|
||||
[Git]: https://git-scm.com/downloads
|
||||
[GNU Tar]: https://www.gnu.org/software/tar/
|
||||
[BSD Tar]: https://man.openbsd.org/tar
|
||||
[Source Code Pro]: https://adobe-fonts.github.io/source-code-pro/
|
||||
[Nanum Gothic]: https://fonts.google.com/specimen/Nanum+Gothic
|
||||
[Arial Unicode MS]: https://docs.microsoft.com/en-us/typography/font-list/arial-unicode-ms
|
||||
[MS Gothic]: https://docs.microsoft.com/en-us/typography/font-list/ms-gothic
|
||||
[Lucida Sans Unicode]: https://docs.microsoft.com/en-us/typography/font-list/lucida-sans-unicode
|
||||
[ripgrep]: https://github.com/BurntSushi/ripgrep
|
||||
[ripgrep-installation]: https://github.com/BurntSushi/ripgrep#installation=
|
||||
[ag]: https://github.com/ggreer/the_silver_searcher
|
||||
[pt]: https://github.com/monochromegane/the_platinum_searcher
|
||||
[ack]: https://github.com/beyondgrep/ack3
|
||||
[GNU Grep]: https://www.gnu.org/software/grep/
|
||||
[BSD Grep]: https://man.openbsd.org/grep
|
||||
[Homebrew]: https://brew.sh
|
||||
[Scoop]: https://scoop.sh
|
||||
|
||||
[spacemacs-desktop]: https://github.com/emacs-mirror/emacs/blob/master/etc/emacs.desktop
|
||||
[icon-repository]: https://github.com/nashamri/spacemacs-logo
|
||||
[icon-mac-instructions]: https://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/
|
||||
|
||||
[so-server-unsafe]: https://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start
|
||||
|
||||
[latest tags]: https://github.com/syl20bnr/spacemacs/tags
|
||||
|
||||
[quote01]: https://gitter.im/syl20bnr/spacemacs?at=568e627a0cdaaa62045a7df6
|
||||
[quote02]: https://gitter.im/syl20bnr/spacemacs?at=5768456c6577f032450cfedb
|
||||
[build_source]: https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html
|
||||
[Bountysource]: https://salt.bountysource.com/teams/spacemacs
|
||||
[Source Code Pro]: https://github.com/adobe-fonts/source-code-pro
|
||||
[Spacemacs Shop]: https://shop.spreadshirt.com/spacemacs-shop
|
||||
[Git]: https://git-scm.com/downloads
|
||||
[spacemacs-desktop]: https://github.com/emacs-mirror/emacs/blob/master/etc/emacs.desktop
|
||||
|
||||
[Spacemacs logo]: https://github.com/nashamri/spacemacs-logo
|
||||
[Nasser Alshammari]: https://github.com/nashamri
|
||||
[creativecommons-4]: https://creativecommons.org/licenses/by-sa/4.0/
|
||||
[ripgrep-homebrew]: https://formulae.brew.sh/formula/ripgrep
|
||||
|
||||
[Spacemacs Shop]: https://shop.spreadshirt.com/spacemacs-shop
|
||||
[Bountysource]: https://salt.bountysource.com/teams/spacemacs
|
||||
|
|
Reference in a new issue