% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/htc-gen-executable.R
\name{htc_gen_executable}
\alias{htc_gen_executable}
\title{Generate an HTCondor executable shell script for an R job}
\usage{
htc_gen_executable(
  output_file = "job.sh",
  r_script = NULL,
  results_folder = "results-folder",
  mode = "single",
  set_executable = TRUE,
  verbose = FALSE,
  comments = FALSE,
  output = "."
)
}
\arguments{
\item{output_file}{A character string. Name of the shell script to write.
Must end in \code{".sh"}. Defaults to \code{"job.sh"}.}

\item{r_script}{A character string. Name of the R script that HTCondor
will run inside the container, e.g. \code{"analysis.R"}. Must be supplied
explicitly -- there is no default. If you used
\code{toolero::create_qmd(use_purl = TRUE)}, the script is the \code{.R} file
produced by \code{purl.R} after rendering.}

\item{results_folder}{A character string. Name of the folder created
inside the container to hold job outputs before compression. Defaults
to \code{"results-folder"}.}

\item{mode}{A character string. Execution mode. \code{"single"} (the default)
runs the R script without a positional argument, producing a single
fixed-name results tarball. \code{"multiple"} passes the subset filename
as a positional argument via \verb{$\{1\}}, producing a per-job tarball named
\verb{$\{1\}-results.tar.gz}. Must match the \code{mode} used in
\code{\link[=htc_gen_submit]{htc_gen_submit()}}.}

\item{set_executable}{Logical. If \code{TRUE}, sets executable permissions on
the generated script via \code{Sys.chmod()} so the file is ready to copy to
the CHTC submit node without any additional steps. Defaults to \code{TRUE}.
Set to \code{FALSE} if you prefer to manage permissions manually, in which
case you must run \code{chmod +x} on the script before submitting your job.}

\item{verbose}{Logical. If \code{TRUE}, prints progress messages as each
section of the script is written. Defaults to \code{FALSE}.}

\item{comments}{Logical. If \code{TRUE}, annotates each section with an
explanatory comment describing what the line does. Useful for
researchers learning the HTCondor executable script conventions.
Defaults to \code{FALSE}.}

\item{output}{A character string. Directory where the shell script will
be written. Defaults to \code{"."} (current working directory).}
}
\value{
Called for its side effects. Writes a bash script to
\code{file.path(output, output_file)} and sets executable permissions when
\code{set_executable = TRUE}. Returns \code{invisible(NULL)}.
}
\description{
\code{htc_gen_executable()} writes a ready-to-use bash script (\code{.sh}) that
HTCondor runs inside the container for each job. The script creates a
results folder, runs the R script via \code{Rscript}, and compresses the
results into a tarball for transfer back to the submit node.
}
\section{Relationship to htc_gen_submit()}{

The executable script generated by \code{htc_gen_executable()} is the file
referenced by the \code{executable} argument in \code{\link[=htc_gen_submit]{htc_gen_submit()}}. The two
functions should always use the same \code{mode}. In \code{"multiple"} mode,
HTCondor passes each subset filename to the script as \verb{$\{1\}}, which is
forwarded to the R script as a positional argument. The R script must
be written to accept this argument -- the recommended approach is
\code{toolero::detect_execution_context()}:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{context <- toolero::detect_execution_context()

input_file <- switch(context,
  interactive = "data/penguins.csv",
  quarto      = params$input_file,
  rscript     = commandArgs(trailingOnly = TRUE)[1]
)
}\if{html}{\out{</div>}}
}

\examples{
# Single-job executable script
htc_gen_executable(r_script = "analysis.R", output = tempdir())

# Multiple-job executable script
htc_gen_executable(
  r_script = "analysis.R",
  mode     = "multiple",
  output   = tempdir()
)

# Custom R script name with annotations
htc_gen_executable(
  output_file = "run.sh",
  r_script    = "run-analysis.R",
  comments    = TRUE,
  verbose     = TRUE,
  output      = tempdir()
)
}
