emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Tim Landscheidt <tim@tim-landscheidt.de>
To: emacs-orgmode@gnu.org
Subject: Best practice for writing and debugging shell source blocks?
Date: Tue, 24 Oct 2023 14:54:48 +0000	[thread overview]
Message-ID: <87pm14qddz.fsf@vagabond.tim-landscheidt.de> (raw)

Hi,

inspired by "Literate DevOps"
(https://howardism.org/Technical/Emacs/literate-devops.html),
I want to document some "stuff" in an Org file with the goal
to be able to replay the steps done in the future so that I
can either recreate the same "product" or variations there-
of.

My actual topic involves (inter alia) containers, but for
simplicity, let us assume that I want to document the se-
quence of shell commands:

| $ mktemp
| /tmp/tmp.gSffc4XtQ0
| $ echo a >> /tmp/tmp.gSffc4XtQ0
| $ echo b >> /tmp/tmp.gSffc4XtQ0
| $ fgrep -x a /tmp/tmp.gSffc4XtQ0
| a
| $

In other words: An "entity" is created and its identifier
shown, this entity is then referenced by this identifier,
changed and queried.

If I put the shell commands in one source block each:

| #+NAME: create-temporary-file
| #+BEGIN_SRC sh
| mktemp
| #+END_SRC

| #+BEGIN_SRC sh :var tmpfile=create-temporary-file
| echo a >> $tmpfile
| #+END_SRC

| #+BEGIN_SRC sh :var tmpfile=create-temporary-file
| echo b >> $tmpfile
| #+END_SRC

| #+BEGIN_SRC sh :var tmpfile=create-temporary-file
| fgrep -x a $tmpfile
| #+END_SRC

and then evaluate the last source block, it calls the source
block create-temporary-file, then searches the (empty) file
and fails, i. e. the second and third source blocks are not
evaluated at all.  (Dealing with failing shell commands is
another headache—thankfully, the trick at
https://emacs.stackexchange.com/questions/59875/org-src-block-does-not-return-any-output
(provide header arguments :prologue "exec 2>&1" and
:epilogue ":") works reasonably well.)

Adding more to the confusion, if I manually evaluate the
first source block (create-temporary-file), it produces for
example:

| #+RESULTS: create-temporary-file
| : /tmp/tmp.lOKZtyJ124

If I then evaluate the last source block (again), the first
code block gets called, but its (different) result gets only
passed to the last source block and used there, while the
"#+RESULTS" section stays the same.

The same thing happens if I add ":session my-test" to all
source blocks, except that I get an additional buffer
"my-test" with the content:

| mktemp
| sh-5.2$ echo 'org_babel_sh_eoe'
| /tmp/tmp.e19GfJsH7w
| sh-5.2$ org_babel_sh_eoe
| sh-5.2$ tmpfile='/tmp/tmp.e19GfJsH7w'
| sh-5.2$ fgrep -x a $tmpfile
| sh-5.2$ echo 'org_babel_sh_eoe'
| org_babel_sh_eoe
| sh-5.2$

where the "mixed" output of "mktemp" and "echo
'org_babel_sh_eoe'" does not necessarily instill confidence
to run commands that are destructive in nature.

So what is The Right Way™ to document sequences of shell
commands so that they are evaluated in sequence, being able
to refer to the output of previous commands?  Are there any
obvious collections of examples that I missed?

TIA,
Tim


             reply	other threads:[~2023-10-24 14:55 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-10-24 14:54 Tim Landscheidt [this message]
2023-10-26  9:56 ` Best practice for writing and debugging shell source blocks? Max Nikulin

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87pm14qddz.fsf@vagabond.tim-landscheidt.de \
    --to=tim@tim-landscheidt.de \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).