Function: org-compile-file

org-compile-file is a byte-compiled function defined in org-macs.el.

Signature

(org-compile-file SOURCE PROCESS EXT &optional ERR-MSG LOG-BUF SPEC)

Documentation

Compile a SOURCE file using PROCESS.

See org-compile-file-commands for information on PROCESS, EXT, and SPEC. If PROCESS fails, an error will be raised. The error message can then be refined by providing string ERR-MSG, which is appended to the standard message.

PROCESS must create a file with the same base name and directory as SOURCE, but ending with EXT. The function then returns its filename. Otherwise, it raises an error.

When PROCESS is a list of commands, optional argument LOG-BUF can be set to a buffer or a buffer name. shell-command then uses it for output.

Source Code

;; Defined in ~/.emacs.d/elpa/org-9.8.2/org-macs.el
(defun org-compile-file (source process ext &optional err-msg log-buf spec)
  "Compile a SOURCE file using PROCESS.

See `org-compile-file-commands' for information on PROCESS, EXT, and SPEC.
If PROCESS fails, an error will be raised.  The error message can
then be refined by providing string ERR-MSG, which is appended to
the standard message.

PROCESS must create a file with the same base name and directory
as SOURCE, but ending with EXT.  The function then returns its
filename.  Otherwise, it raises an error.

When PROCESS is a list of commands, optional argument LOG-BUF can
be set to a buffer or a buffer name.  `shell-command' then uses
it for output."
  (let* ((commands (org-compile-file-commands source process ext spec err-msg))
         (output (concat (file-name-sans-extension source) "." ext))
         ;; Resolve symlinks in default-directory to correctly handle
         ;; absolute source paths or relative paths with ..
         (relname (if (file-name-absolute-p source)
                      (let ((pwd (file-truename default-directory)))
                        (file-relative-name source pwd))
                    source))
         (log-buf (and log-buf (get-buffer-create log-buf)))
         (time (file-attribute-modification-time (file-attributes output)))
         exit-status (did-error nil))
    (save-window-excursion
      (dolist (command commands)
        (cond
         ((functionp command)
          ;; We could treat return value of the function
          ;; as return code in shell command, but that would be
          ;; a breaking changed compared to historical behavior.
          ;; Functions might still take care to remove the target file
          ;; (if it already exists) to mark failure.
          (funcall command (shell-quote-argument relname)))
         ((stringp command)
          (let ((shell-command-dont-erase-buffer t))
            (setq exit-status (shell-command command log-buf))
            (when (and (numberp exit-status) (> exit-status 0))
              (setq did-error t)))))))
    ;; Check for process failure.  Output file is expected to be
    ;; located in the same directory as SOURCE.
    ;; Sometimes, the (LaTeX) process fails still producing output.
    ;; Then, assume compilation success. It is way too common for
    ;; LaTeX to throw non-0 exit code yet producing perfectly usable
    ;; pdfs.
    (when (or (not (file-exists-p output))
              ;; non-0 exit code and output not updated.
              (and did-error
                   (not (org-file-newer-than-p output time))))
      (ignore (defvar org-batch-test))
      ;; Display logs when running tests.
      (when (bound-and-true-p org-batch-test)
        (message "org-compile-file log ::\n-----\n%s\n-----\n"
                 (with-current-buffer log-buf (buffer-string))))
      (error
       (format
        "File %S wasn't produced%s"
        output
        (if (org-string-nw-p err-msg)
            (concat "  " (org-trim err-msg))
          err-msg))))
    output))