Emacs configuration

You need to clone this repository. You can use this command to clone:

  git clone https://github.com/Pismice/HEIG_ZIG.git

To use Emacs with this documentation, you need to follow these instructions.

Launch Emacs and you will have a welcome window. To navigate to this documentation, you need to use the following shortcut: C-x C-f (ctrl-x ctrl-f). This will open a command in the bottom left corner. With this command, you can select the path of the file you want to open.

If you want to open the introduction file, you need in the first place enter the directory path where you have cloned this documentation. When you are in the root directory of the documentation, you can find all the documentation files in the directory:

./content/docs/*

And this introduction file can be found in :

./content/docs/introduction.org

More Emacs documentation can be found here if you want to further tweak your configuration or do other specific things.

Now that we have opened the file, we can then start installing the necessary plugins to use the documentation with Literate programming.

1. Install Zig emacs org babel plugin

To install the plugins that will be used to interact with the example codes, you need to follow the different steps.

Open this introduction.org file with Emacs. Below, you will find instructions to create your Emacs configuration. This configuration will be built interactively.

1.1. First step Place your cursor in the code block below and use C-c C-c (ctrl-c ctrl-c) to evaluate the code below. It will add a shell interpreter inside org-babel configuration, it will be used when shell commands are evaluated.

  (add-to-list 'org-babel-load-languages '(shell . t))
  (org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages)

1.2. Second step The shell command will clone an org babel zig plugin necessary to execute some Zig examples directly in Emacs with Org babel.

The HEADER parameter below (in the code block) configures the directory path by default. You can change the directory where the plugin will be installed (change the argument after the :dir -> /CHANGE-ME).

Once you have changed the HEADER parameter, you can place your cursor in the code block below and use C-c C-c (ctrl-c ctrl-c) to evaluate the code below.

  git clone https://github.com/samuel-schlaeppy/ob-zig.el.git

1. Create an emacs configuration file

In the last section, the plugin Ob-Zig has been installed, this plugin will help to evaluate Zig example codes. To use correctly this plugin, in the code block below, you need to change the string ./PATH-WHERE-THE-OB-ZIG-PLUGIN-IS-INSTALLED/ob-zig.el where you have cloned the plugin ob-zig.el. In addition, you need to change in the code block the string PATH-TO-THE-ZIG-EXECUTABLE to insert the path of the Zig executable.

After that, the following command C-c C-v t (ctrl-c ctrl-v t) will produce a zigIterativeProgramming.el file. This file can be loaded from your emacs configuration (see section below).

  (setq base_dir "~/PATH-WHERE-THE-ZIG-PLUGIN-IS-INSTALLED/ob-zig.el")
  (setq org-babel-zig-compiler "PATH-TO-THE-ZIG-EXECUTABLE")

  (require 'package)
  (add-to-list 'package-archives
               '("melpa" . "https://melpa.org/packages/"))
  (package-initialize)
  (package-refresh-contents)

  (defun install-custom-pkg (pck)
    (if (featurep pck)
        (message "The package %s is already installed !" pck)
      (package-install pck)
      ))

  (install-custom-pkg 'zig-mode)
  (install-custom-pkg 'lsp-mode)
  (require 'lsp-mode)
  (add-hook 'zig-mode-hook #'lsp)

  (let ((local-file-path (expand-file-name "ob-zig.el" base_dir)))
    (setq org-babel-zig-compiler local-file-path)
    (load-file local-file-path)
    )

  (custom-set-variables
   ;; custom-set-variables was added by Custom.
   ;; If you edit it by hand, you could mess it up, so be careful.
   ;; Your init file should contain only one such instance.
   ;; If there is more than one, they won't work right.
   '(org-babel-load-languages '((C . t) (emacs-lisp . t) (shell . t))))

1. Execute the configuration file from the configuration

You can put the code below in your init.el it will load the file produced before and load the necessary package to learn Zig with literate programming. But you need the specify the directory path of the zigIterativeProgramming.el file (first line below). (the init.el can be found in ~/.emacs.d/ or can be created in ~/.config/emacs/

  (let ((file_dir "~/PATH-TO-THE-zigIterativeProgramming-file"))
  (load-file (expand-file-name "zigIterativeProgramming.el" file_dir)))