# elispcomp - Compile Emacs Lisp code from the command-line
The `elispcomp` command line tool allows compiling Emacs Lisp (Elisp) code directly from the terminal or from a shell script. It facilitates the generation of optimized `.elc` (byte-compiled) and `.eln` (native-compiled) files, which can significantly improve the performance of Emacs.
The command line tool executes a headless instance of Emacs and Elisp that recursively scans the specified directories, byte compiling and native compiling all the `.el` files that haven't been compiled yet. It supports various configuration options, allowing you to adapt the compilation process to suit your needs.
When configured appropriately, Emacs can compile to both `.elc` and `.eln` files. However, for those who wish to automate the background compilation of `.el` files using a script, the `elispcomp` command-line tool can be beneficial in ensuring that their Emacs setup remains up-to-date without manual intervention and without starting an Emacs instance.
## Installation
To get started with `elispcomp`, you can install it using `pip`:
```
pip install --user elispcomp
```
This command installs `elispcomp` and places the executable in your `~/.local/bin/` directory, making it easily accessible from your command line.
## Requirements
- Python 3
- Emacs >= 28
## Usage
The `elispcomp` command line tool is straightforward to use.
First example: To compile all `.el` files located in the `~/.emacs.d/lisp` directory:
```
elispcomp ~/.emacs.d/lisp
```
Second example: To compile all `.el` files located in the `~/.emacs.d/lisp` directory, and store the native-compiled files in the `~/.emacs.d/eln-cache` directory:
```
elispcomp --eln-cache ~/.emacs.d/eln-cache ~/.emacs.d/lisp
```
## Command line options
```
usage: elispcomp [--option] [N]
Recursively byte and native compile .el files.
positional arguments:
N The directories to be scanned recursively by Emacs to locate the '.el'
files for compilation.
options:
-h, --help show this help message and exit
-c ELN_CACHE, --eln-cache ELN_CACHE
The eln-cache directory where Emacs stores the compiled native compiled
code. Defaults to the default Emacs eln-cache directory.
-e EMACS_BIN, --emacs-bin EMACS_BIN
Path to the Emacs binary. Defaults: emacs
-j JOBS, --jobs JOBS Specify the number of parallel jobs for compilation. Default: Half the
number of available CPUs
-b, --disable-byte-compile, --disable-byte-comp
Disable byte compile. Default: enabled
-n, --disable-native-compile, --disable-native-comp
Disable native compilation. Default: enabled
-i LOAD_PATH, --load-path LOAD_PATH
Recursively adds the subdirectories of the specified directory to the
Emacs `load-path`. This option can be used multiple times to include
several directories.
-a, --ensure-native-compile-available, --ensure-native-comp-available
Fail when native compilation is not available.
```
## Frequently asked questions
### Can't I achieve the same result using Emacs?
Indeed, when configured appropriately, Emacs can compile to both `.elc` and `.eln` files.
The `elispcomp` command-line tool is an Emacs wrapper that makes it easy to compile Emacs Lisp (Elisp) code directly from the terminal or from a script. It provides options and ensures that the byte compilation and native compilation processes are truly finished before quitting with an error code.
The `elispcomp` command-line tool can also be used in conjunction with other tools like `parallel` to speed up the compilation process.
### How does the author utilize elispcomp?
The author utilizes the `elispcomp` tool to compile multiple Emacs Lisp files across various machines and Emacs versions. With a diverse range of machines and Emacs versions in his workflow, `elispcomp` ensures consistent compilation results and compatibility.
Additionally, the author employs the `parallel` command-line tool to enhance the efficiency of the byte-compilation process. This tool allows the distribution of the compilation workload across multiple processors, significantly accelerating the process.
### Is elispcomp written in Python or Elisp?
Most of what elispcomp does is written in Elisp, including scanning directories, which is handled by the Emacs functions `(byte-recompile-directory)` and `(native-compile-async)`. Python handles the command-line interface (arguments), and Emacs and the Elisp code does the rest (byte compilation, native compilation, and waiting until all the .el files are byte compiled and native compiled).
## License
Copyright (c) 2024 [James Cherti](https://www.jamescherti.com)
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
## Links
- [elispcomp @GitHub](https://github.com/jamescherti/elispcomp)
- [elispcomp @PyPI](https://pypi.org/project/elispcomp/)
- [Article: Introducing elispcomp: Compiling Elisp code directly from the command line](https://www.jamescherti.com/elispcomp-elisp-compilation-from-command-line/)
Raw data
{
"_id": null,
"home_page": "https://github.com/jamescherti/elispcomp",
"name": "elispcomp",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": null,
"author": "James Cherti",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e1/18/731e96a9a4f82a7b8c0baef10b0af23925c88b17b92fef50e8f3450044aa/elispcomp-1.0.9.tar.gz",
"platform": null,
"description": "# elispcomp - Compile Emacs Lisp code from the command-line\n\nThe `elispcomp` command line tool allows compiling Emacs Lisp (Elisp) code directly from the terminal or from a shell script. It facilitates the generation of optimized `.elc` (byte-compiled) and `.eln` (native-compiled) files, which can significantly improve the performance of Emacs.\n\nThe command line tool executes a headless instance of Emacs and Elisp that recursively scans the specified directories, byte compiling and native compiling all the `.el` files that haven't been compiled yet. It supports various configuration options, allowing you to adapt the compilation process to suit your needs.\n\nWhen configured appropriately, Emacs can compile to both `.elc` and `.eln` files. However, for those who wish to automate the background compilation of `.el` files using a script, the `elispcomp` command-line tool can be beneficial in ensuring that their Emacs setup remains up-to-date without manual intervention and without starting an Emacs instance.\n\n## Installation\n\nTo get started with `elispcomp`, you can install it using `pip`:\n```\npip install --user elispcomp\n```\n\nThis command installs `elispcomp` and places the executable in your `~/.local/bin/` directory, making it easily accessible from your command line.\n\n## Requirements\n\n- Python 3\n- Emacs >= 28\n\n## Usage\n\nThe `elispcomp` command line tool is straightforward to use.\n\nFirst example: To compile all `.el` files located in the `~/.emacs.d/lisp` directory:\n```\nelispcomp ~/.emacs.d/lisp\n```\n\nSecond example: To compile all `.el` files located in the `~/.emacs.d/lisp` directory, and store the native-compiled files in the `~/.emacs.d/eln-cache` directory:\n```\nelispcomp --eln-cache ~/.emacs.d/eln-cache ~/.emacs.d/lisp\n```\n\n## Command line options\n\n```\nusage: elispcomp [--option] [N]\n\nRecursively byte and native compile .el files.\n\npositional arguments:\n N The directories to be scanned recursively by Emacs to locate the '.el'\n files for compilation.\n\noptions:\n -h, --help show this help message and exit\n -c ELN_CACHE, --eln-cache ELN_CACHE\n The eln-cache directory where Emacs stores the compiled native compiled\n code. Defaults to the default Emacs eln-cache directory.\n -e EMACS_BIN, --emacs-bin EMACS_BIN\n Path to the Emacs binary. Defaults: emacs\n -j JOBS, --jobs JOBS Specify the number of parallel jobs for compilation. Default: Half the\n number of available CPUs\n -b, --disable-byte-compile, --disable-byte-comp\n Disable byte compile. Default: enabled\n -n, --disable-native-compile, --disable-native-comp\n Disable native compilation. Default: enabled\n -i LOAD_PATH, --load-path LOAD_PATH\n Recursively adds the subdirectories of the specified directory to the\n Emacs `load-path`. This option can be used multiple times to include\n several directories.\n -a, --ensure-native-compile-available, --ensure-native-comp-available\n Fail when native compilation is not available.\n```\n\n## Frequently asked questions\n\n### Can't I achieve the same result using Emacs?\n\nIndeed, when configured appropriately, Emacs can compile to both `.elc` and `.eln` files.\n\nThe `elispcomp` command-line tool is an Emacs wrapper that makes it easy to compile Emacs Lisp (Elisp) code directly from the terminal or from a script. It provides options and ensures that the byte compilation and native compilation processes are truly finished before quitting with an error code.\n\nThe `elispcomp` command-line tool can also be used in conjunction with other tools like `parallel` to speed up the compilation process.\n\n### How does the author utilize elispcomp?\n\nThe author utilizes the `elispcomp` tool to compile multiple Emacs Lisp files across various machines and Emacs versions. With a diverse range of machines and Emacs versions in his workflow, `elispcomp` ensures consistent compilation results and compatibility.\n\nAdditionally, the author employs the `parallel` command-line tool to enhance the efficiency of the byte-compilation process. This tool allows the distribution of the compilation workload across multiple processors, significantly accelerating the process.\n\n### Is elispcomp written in Python or Elisp?\n\nMost of what elispcomp does is written in Elisp, including scanning directories, which is handled by the Emacs functions `(byte-recompile-directory)` and `(native-compile-async)`. Python handles the command-line interface (arguments), and Emacs and the Elisp code does the rest (byte compilation, native compilation, and waiting until all the .el files are byte compiled and native compiled).\n\n## License\n\nCopyright (c) 2024 [James Cherti](https://www.jamescherti.com)\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.\n\n## Links\n\n- [elispcomp @GitHub](https://github.com/jamescherti/elispcomp)\n- [elispcomp @PyPI](https://pypi.org/project/elispcomp/)\n- [Article: Introducing elispcomp: Compiling Elisp code directly from the command line](https://www.jamescherti.com/elispcomp-elisp-compilation-from-command-line/)\n",
"bugtrack_url": null,
"license": null,
"summary": "Compiling Emacs Lisp code from the command-line",
"version": "1.0.9",
"project_urls": {
"Homepage": "https://github.com/jamescherti/elispcomp"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f340abe7bef4d71e49a2bc913f437bdf3760b8362ba34fd7e7151a6a6fcfed7",
"md5": "ee849a38c9bcc0b329f331cdffc89451",
"sha256": "131433151121da76b3d0018c789a7a517ea29584e4fcb28af40eaba3b6910d21"
},
"downloads": -1,
"filename": "elispcomp-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ee849a38c9bcc0b329f331cdffc89451",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 10234,
"upload_time": "2024-07-23T17:39:17",
"upload_time_iso_8601": "2024-07-23T17:39:17.271697Z",
"url": "https://files.pythonhosted.org/packages/7f/34/0abe7bef4d71e49a2bc913f437bdf3760b8362ba34fd7e7151a6a6fcfed7/elispcomp-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e118731e96a9a4f82a7b8c0baef10b0af23925c88b17b92fef50e8f3450044aa",
"md5": "c08ac8ca5e055e719de1766aa25ec3ad",
"sha256": "455da02d9b0a1ecb2f48b1d92b67c3cb1ae678f9701a52687426c46aa46793f8"
},
"downloads": -1,
"filename": "elispcomp-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "c08ac8ca5e055e719de1766aa25ec3ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 10969,
"upload_time": "2024-07-23T17:39:19",
"upload_time_iso_8601": "2024-07-23T17:39:19.085970Z",
"url": "https://files.pythonhosted.org/packages/e1/18/731e96a9a4f82a7b8c0baef10b0af23925c88b17b92fef50e8f3450044aa/elispcomp-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-23 17:39:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jamescherti",
"github_project": "elispcomp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "elispcomp"
}
JSON
