UP | HOME

Running Emacs as a Portable Application
For Windows

Table of Contents

1. About

I have created this page to document what I have learned in trying to create an Emacs system that can run as a portable application from a USB drive on a Windows system. My initial inspiration came from this article.

2. Why Run Emacs as a Portable App?

Here are some reasons why I run Emacs as a portable application:

  • Access your Org Mode agenda on the go from any Windows computer
  • Always have access to a double-pane file manager such as Dired or Sunshine commander even on Windows
  • The ability to use the Emacs key bindings that have become muscle memory after much use
  • Emacs Eshell will work even on a Windows system as many Linux shell commands are rewritten in Emacs Lisp
  • Create LaTeX documents in Windows without having to use another editor
  • Check your email using Gnus or some other Emacs mail reader and take your configuration with you
  • Have acess to all the power of Emacs and you custom configuration anywhere you go

3. Process

Here is the process I used to make Emacs run off of a USB flash drive:

Note: On slow systems, I have found it very important to verify the speed of any flash drive you use to launch Emacs. I have found that the difference between two USB 3.0 flash drives can change emacs-init-time from minutes to seconds with the right flash drive. Apparently, not all USB 3.0 drive are alike.

  1. Download Emacs from the Gnu.org ftp site.
  2. Extract the .zip file to your flash drive into a new directory (I recommend calling it emacs).
  3. Create a .emacs.d directory on your flash drive.
  4. Create a runemacs.bat file to launch Emacs containing the following lines:

    • Set Emacs home directory to the flash drive label so files are not saved to the host system. 

      rem Set the Emacs home directory to the drive label of the flash drive.
set HOME=%~dp0

    • Create an environment variable to tell Emacs it was launched as a portable application. I do this so I can use the same Emacs configuration for all instances of Emacs whether I am running it as a portable application or not. This lets me include code in init.el to check if Emacs was launched as a portable application. If Emacs detects it was launched as a portable application, I can call on different functions to set up Emacs differently. 

      rem Set an evironment variable to tell Emacs that it is running portably
set EMACS_PORTABLE="Y"

      Now, in your init.el configuration file, you can use the following code to check if Emacs was called by executing runemacs.bat in any if or when statement: 

      (string= (getenv "EMACS_PORTABLE") "Y")

      In Emacs, I create my init.el file from Org Mode in a file called init.org. I use noweb syntax to call it with <<portable_check>> so I can reuse the code easily. For an example see <<portable_check>> in 4.1.

    • Call the Emacs executable and launch it.

      rem Find the Emacs executable and execute it.
"%~dp0/emacs/bin/runemacs.exe" %
  5. Enjoy!

4. Access Org Agenda Files from the Cloud

My biggest reason for using Emacs as a portable application is the power of Org Mode. I find that as an organization and task management system, nothing else quite compares and I cannot find any system that I like better. I have tried many other systems and nothing else has been as helpful for me. Plus, it lets me use Emacs which is something I greatly enjoy so I am more likely to check my agenda if it gives me an excuse to use Emacos.

One of the biggest problems with Org Mode, however, has been how it is not based in the cloud. It took me quite a long time to figure out how to solve this problem and here is the solution I have come up with:

  1. Store all your org-agenda files in the cloud (I use Dropbox)

  2. Download rclone to your flash drive. As mentioned on the rclone website:

    Rclone is single executable (rclone, or rclone.exe on Windows) that you can simply download as a zip archive and extract into a location of your choosing. See the install documentation for more details

  3. Use Emacs eshell to call rclone.exe using the --config-file option to save the config file to your USB flash drive
  4. Run rclone.exe sync --config /path/to/config/file remote: ~/local_folder to download your Org Mode agenda files from your cloud site
  5. Use Org Mode as normal
  6. Sync the changes back to the cloud with rclone.exe sync --config /path/to/config/file remote: ~/local_folder remote:

4.1. Syncing Org Files Automatically

In order to avoid human error in this process, I have added functions to my init.el file to do this work for me automatically:

This function will create an Emacs Lisp function in Emacs to run rclone: 

(defun rclone-sync (source dest &optional rclone-path rclone-config)
  "Sync DEST with SOURCE using rclone.
The path to the rlcone executable can be set with RCLONE-PATH.
The rclone configuration can be set with RCLONE-CONFIG."
  (interactive)
  (let ((rclone-path (or rclone-path "rclone"))
        (rclone-config (or rclone-config nil))
        (config-option
         (if rclone-config
             (concat " --config " rclone-config)
           (nil))))
    (eshell-command
     (concat rclone-path
             config-option
             " -vP sync "
             source
             " "
             dest))))

I then run rclone when Emacs starts up and add a hook to run when Emacs is closed with the kill-emacs-hook (killed): 

(when <<portable_check>>
  (let ((rclone-remote "dropbox:")
        (rclone-local "~/Dropbox")
        (rclone-path  "~/rclone/rclone.exe")
        (rclone-conf "~/rclone/rclone.conf"))
    (rclone-sync rclone-remote
                 rclone-local
                 rclone-path
                 rclone-conf)
    (add-hook 'kill-emacs-hook (lambda ()
                                 (rclone-sync rclone-local
                                              rclone-remote
                                              rclone-path
                                              rclone-conf)))))

Note: you will want to change the variables to match your own setup. I am using Dropbox for syncing my agenda files but any service supported by rclone will work.

This will cause Emacs to sync my Org Mode agenda files and anything else in my Dropbox automatically by downloading all my Dropbox files to my flash drive into a folder called Dropbox.

5. Extending Portable Emacs

In order to replicate all the functionality of Linux that I use when I install it to a hard drive, I installed the following dependencies onto the portable flash drive:

Git
If you have the PortableApps.com platform installed on your flash drive. You can install GitPortable and telling Emacs where the git executable can be found. This is necessary for straight.el to work, to pull an updated Emacs config from Github, and for committing source code to Github.
Hunspell

Spell checking does not work by default in Windows as ispell and aspell are not installed. To overcome this issue, a portable version of hunspell can be installed directly into the .emacs.d directory from ezwinports and set as the ispell-program-name: 

(if (eq system-type 'windows-nt)
    (progn (setq ispell-program-name (expand-file-name "~/.emacs.d/hunspell/bin/hunspell.exe"))
           (setq ispell-personal-dictionary "~/.emacs.d/hunspell_en_US")
           (setq ispell-local-dictionary "en_US")
           (setq ispell-local-dictionary-alist
                 '(("en_US" "[[:alpha:]]" "[^[:alpha:]]" "[']" nil ("-d" "en_US") nil utf-8))))
  (setq ispell-program-name (whicher "hunspell")))
MiKTeX

MiKTeX provides a portable version that can be installed on a flash drive and will make it possible to create LaTeX documents even if LaTeX libraries are not insalled on the host system. 

(add-to-list 'exec-path "~/PortableApps/GitPortable/App/Git/bin")
PDFTools
If you use the PDFtools package on Emacs, if you have access to a Windows system where you have administrator access and msys2 installed, you can install and compile PDFTools using that system so it will be ready when you take it on the road.
PlantUML

In order to be able to make flowcharts and other diagrams with PlantUML, I downloaded the PlantUML .jar file to the .emacs.d folder on the USB drive and told Org Mode how to find it with the following addition to init.el: 

(org-plantuml-jar-path (expand-file-name "~/.emacs.d/plantuml/plantuml.jar"))
Rclone
Since Rclone can be run as a portable app, I use it to sync files between my portable Emacs on the flash drive and my other Emacs instances installed on hard drives. See above.

6. About This Page

This page was written in Emacs Org Mode and exported to HTML using the Org Mode export engine. This wonder "ReadTheOrg" theme along with how to use it can be found at this link.

Date: 2022-03-30 Wed 00:00

Author: Thomas Freeman

Created: 2022-05-15 Sun 22:10

Validate