Change the name "layout" to "spec", e.g. config$spec

NEWS.md

@@ -33,6 +33,7 @@
 - Write a complete project structure in `use_drake()` (#1097, @lorenzwalthert, @tjmahr).
 - Add a minor logger note to say how many dynamic sub-targets are registered at a time (#1102, @kendonB).
 - Handle dependencies that are dynamic targets but not declared as such for the current target (#1107).
+- Internally, the "layout" data structure is now called the "workflow specification", or "spec" for short. The spec is `drake`'s interpretation of the plan. In the plan, all the dependency relationships among targets and files are *implicit*. In the spec, they are all *explicit*. We get from the plan to the spec using static code analysis, e.g. `analyze_code()`.
 
 
 # Version 7.8.0

R/backend_clustermq.R

@@ -140,32 +140,32 @@ cmq_send_target <- function(target, config) {
     manage_memory(target = target, config = config, jobs = 1)
     deps <- cmq_deps_list(target, config)
   }
-  layout <- hpc_layout(target, config)
+  spec <- hpc_spec(target, config)
   ht_is_subtarget <- config$ht_is_subtarget
   config$workers$send_call(
     expr = drake::cmq_build(
       target = target,
       meta = meta,
       deps = deps,
-      layout = layout,
+      spec = spec,
       ht_is_subtarget = ht_is_subtarget,
       config = config
     ),
     env = list(
       target = target,
       meta = meta,
       deps = deps,
-      layout = layout,
+      spec = spec,
       ht_is_subtarget = ht_is_subtarget
     )
   )
 }
 
 cmq_deps_list <- function(target, config) {
-  layout <- config$layout[[target]]
-  keys_static <- layout$deps_build$memory
-  keys_dynamic <- layout$deps_dynamic_whole
-  keys_subtargets <- layout$deps_dynamic
+  spec <- config$spec[[target]]
+  keys_static <- spec$deps_build$memory
+  keys_dynamic <- spec$deps_dynamic_whole
+  keys_subtargets <- spec$deps_dynamic
   vals_static <- lapply(
     keys_static,
     get,
@@ -202,12 +202,12 @@ cmq_deps_list <- function(target, config) {
 #' @param target Target name.
 #' @param meta List of metadata.
 #' @param deps Named list of target dependencies.
-#' @param layout Internal, part of the full `config$layout`.
+#' @param spec Internal, part of the full `config$spec`.
 #' @param ht_is_subtarget Internal, part of `config`
 #' @param config A [drake_config()] list.
-cmq_build <- function(target, meta, deps, layout, ht_is_subtarget, config) {
+cmq_build <- function(target, meta, deps, spec, ht_is_subtarget, config) {
   config$logger$minor("build on an hpc worker", target = target)
-  config$layout <- layout
+  config$spec <- spec
   config$ht_is_subtarget <- ht_is_subtarget
   do_prework(config = config, verbose_packages = FALSE)
   caching <- hpc_caching(target, config)

R/backend_future.R

@@ -82,12 +82,12 @@ ft_launch_worker <- function(target, meta, protect, config) {
     manage_memory(target = target, config = config, downstream = protect)
   }
   DRAKE_GLOBALS__ <- NULL # Avoid name conflicts with other globals.
-  layout <- hpc_layout(target, config)
+  spec <- hpc_spec(target, config)
   globals <- future_globals(
     target = target,
     meta = meta,
     config = config$ft_config,
-    layout = layout,
+    spec = spec,
     ht_is_subtarget = config$ht_is_subtarget,
     protect = protect
   )
@@ -98,13 +98,13 @@ ft_launch_worker <- function(target, meta, protect, config) {
         target = DRAKE_GLOBALS__$target,
         meta = DRAKE_GLOBALS__$meta,
         config = DRAKE_GLOBALS__$config,
-        layout = DRAKE_GLOBALS__$layout,
+        spec = DRAKE_GLOBALS__$spec,
         ht_is_subtarget = DRAKE_GLOBALS__$ht_is_subtarget,
         protect = DRAKE_GLOBALS__$protect
       ),
       globals = globals,
       label = target,
-      resources = as.list(layout$resources)
+      resources = as.list(spec$resources)
     ),
     target = target
   )
@@ -114,7 +114,7 @@ future_globals <- function(
   target,
   meta,
   config,
-  layout,
+  spec,
   ht_is_subtarget,
   protect
 ) {
@@ -123,7 +123,7 @@ future_globals <- function(
       target = target,
       meta = meta,
       config = config,
-      layout = layout,
+      spec = spec,
       ht_is_subtarget = ht_is_subtarget,
       protect = protect
     )
@@ -161,11 +161,11 @@ future_build <- function(
   target,
   meta,
   config,
-  layout,
+  spec,
   ht_is_subtarget,
   protect
 ) {
-  config$layout <- layout
+  config$spec <- spec
   config$ht_is_subtarget <- ht_is_subtarget
   caching <- hpc_caching(target, config)
   if (identical(caching, "worker")) {

R/cache.R

@@ -617,6 +617,7 @@ cached <- function(
 #' @param plan A drake plan.
 #' @examples
 #' \dontrun{
+#' isolate_example("cache_planned() example", {
 #' plan <- drake_plan(w = 1)
 #' make(plan)
 #' cached_planned(plan)
@@ -628,7 +629,6 @@ cached <- function(
 #' make(plan)
 #' cached_planned(plan)
 #' cached()
-#' }
 #' })
 #' }
 cached_planned <- function(
@@ -661,6 +661,7 @@ cached_planned <- function(
 #' @param plan A drake plan.
 #' @examples
 #' \dontrun{
+#' isolate_example("cache_unplanned() example", {
 #' plan <- drake_plan(w = 1)
 #' make(plan)
 #' cached_unplanned(plan)
@@ -675,7 +676,6 @@ cached_planned <- function(
 #' cached()
 #' clean(list = cached_unplanned(plan))
 #' cached()
-#' }
 #' })
 #' }
 cached_unplanned <- function(

R/create_drake_graph.R

@@ -1,17 +1,17 @@
 create_drake_graph <- function(
   plan,
-  layout,
+  spec,
   targets,
   cache,
   jobs,
   logger
 ) {
   config <- list(plan = plan, jobs = jobs, logger = logger, cache = cache)
   edges <- memo_expr(
-    cdg_create_edges(config, layout),
+    cdg_create_edges(config, spec),
     cache,
     plan,
-    layout
+    spec
   )
   memo_expr(
     cdg_finalize_graph(edges, targets, config),
@@ -21,9 +21,9 @@ create_drake_graph <- function(
   )
 }
 
-cdg_create_edges <- function(config, layout) {
+cdg_create_edges <- function(config, spec) {
   edges <- lightly_parallelize(
-    X = layout,
+    X = spec,
     FUN = cdg_node_to_edges,
     jobs = config$jobs,
     config = config