There are many build systems, and more uses for build systems (see Powers et al. 2002, sec. 11.10 and 11.11).
I have been using the unix make utility when developing R packages since 2012. But sometimes I get caught on a machine where make is not available and where I am not entitled to install it1.
This is why I wrote fakemake: to build an R package conditionally on the modification times of (file) dependencies without having to rely on external software. If you have any proper build system at hand: stick to it, do not use fakemake.
Throughout this vignette I use R’s temporary directory, often by using withr::with_dir(tempdir(), ...). Because this is a vignette and the codes are examples. In real life, we would skip the temporary directory stuff.
Vignettes are built using knitr, which itself uses sink(). As sink() is central to fakemake for redirecting output to files in the make chain, I have to disable some of knitr’s output here and there. Don’t worry, it’s just because knitr and fakemake both want to use sink() exclusively and it only affects vignettes built with knitr.
A makelist is the fakemake`s representation of a Makefile. It’s just a list of lists. Look at the minimal makelist provided by fakemake:
str(fakemake::provide_make_list("minimal", clean_sink = TRUE))## List of 4
## $ :List of 3
## ..$ target : chr "all.Rout"
## ..$ prerequisites: chr [1:2] "a1.Rout" "a2.Rout"
## ..$ code : chr "print(\"all\")"
## $ :List of 2
## ..$ target: chr "a2.Rout"
## ..$ code : chr "print(\"a2\")"
## $ :List of 3
## ..$ target : chr "a1.Rout"
## ..$ prerequisites: chr "b1.Rout"
## ..$ code : chr "print(\"a1\")"
## $ :List of 2
## ..$ target: chr "b1.Rout"
## ..$ code : chr "print(\"b1\")"Each sublist represents a Makefile’s target rule and has several items: at least a target and either code or prerequisites, possibly both. This makelist would still be a Makefile’s valid representation if target rule #3 with target “a1.Rout” had no (or an empty) code entry.
Other possible target rule entries are:
Suppose we would have a minimal makelist:
ml <- fakemake::provide_make_list("minimal", clean_sink = TRUE)Now build the “all.Rout” target:
withr::with_dir(tempdir(), print(fakemake::make("all.Rout", ml)))## Current target is: all.Rout.## Current target is: a1.Rout.## Current target is: b1.Rout.## Current target is: a2.Rout.## [1] "b1.Rout" "a1.Rout" "a2.Rout" "all.Rout"We can see the files created:
show_file_mtime <- function(files = list.files(tempdir(), full.names = TRUE,
pattern = "^.*\\.Rout")) {
return(file.info(files)["mtime"])
}
show_file_mtime()## mtime
## /tmp/Rtmpf0rak4/a1.Rout 2019-11-28 16:25:04
## /tmp/Rtmpf0rak4/a2.Rout 2019-11-28 16:25:04
## /tmp/Rtmpf0rak4/all.Rout 2019-11-28 16:25:04
## /tmp/Rtmpf0rak4/b1.Rout 2019-11-28 16:25:04If we wait for a second and rerun the build process, we get:
# ensure the modification time would change if the files were recreated
Sys.sleep(1)
withr::with_dir(tempdir(), print(fakemake::make("all.Rout", ml)))## Current target is: all.Rout.## Current target is: a1.Rout.## Current target is: b1.Rout.## Current target is: a2.Rout.## NULLshow_file_mtime()## mtime
## /tmp/Rtmpf0rak4/a1.Rout 2019-11-28 16:25:04
## /tmp/Rtmpf0rak4/a2.Rout 2019-11-28 16:25:04
## /tmp/Rtmpf0rak4/all.Rout 2019-11-28 16:25:04
## /tmp/Rtmpf0rak4/b1.Rout 2019-11-28 16:25:04Nothing changed. Good. Now, we change one file down the build chain:
fakemake::touch(file.path(tempdir(), "b1.Rout"))
withr::with_dir(tempdir(), print(fakemake::make("all.Rout", ml)))## Current target is: all.Rout.## Current target is: a1.Rout.## Current target is: b1.Rout.## Current target is: a2.Rout.## [1] "a1.Rout" "all.Rout"show_file_mtime()## mtime
## /tmp/Rtmpf0rak4/a1.Rout 2019-11-28 16:25:05
## /tmp/Rtmpf0rak4/a2.Rout 2019-11-28 16:25:04
## /tmp/Rtmpf0rak4/all.Rout 2019-11-28 16:25:05
## /tmp/Rtmpf0rak4/b1.Rout 2019-11-28 16:25:05Since a1.Rout depends on b1.Rout and all.Rout depends on a1.Rout, these targets get rebuilt while a2.Rout stays untouched.
Had we touched a1.Rout, b1.Rout would not have been rebuilt:
fakemake::touch(file.path(tempdir(), "a1.Rout"))
withr::with_dir(tempdir(), print(fakemake::make("all.Rout", ml)))## Current target is: all.Rout.## Current target is: a1.Rout.## Current target is: b1.Rout.## Current target is: a2.Rout.## [1] "all.Rout"show_file_mtime()## mtime
## /tmp/Rtmpf0rak4/a1.Rout 2019-11-28 16:25:06
## /tmp/Rtmpf0rak4/a2.Rout 2019-11-28 16:25:04
## /tmp/Rtmpf0rak4/all.Rout 2019-11-28 16:25:06
## /tmp/Rtmpf0rak4/b1.Rout 2019-11-28 16:25:05If you set the force option, you can force the target and all its prerequisites down the build chain to be built:
withr::with_dir(tempdir(), print(fakemake::make("all.Rout", ml, force = TRUE)))## Current target is: all.Rout.## Current target is: a1.Rout.## Current target is: b1.Rout.## Current target is: a2.Rout.## [1] "b1.Rout" "a1.Rout" "a2.Rout" "all.Rout"If you want to force the target itself, but not all its prerequisites, set recursive = FALSE:
withr::with_dir(tempdir(), print(fakemake::make("all.Rout", ml, force = TRUE,
recursive = FALSE)))## Current target is: all.Rout.## Current target is: a1.Rout.## Current target is: b1.Rout.## Current target is: a2.Rout.## [1] "all.Rout"If you find a target rule’s target too hard to type, you can use an alias:
i <- which(sapply(ml, "[[", "target") == "all.Rout")
ml[[i]]["alias"] <- "all"
withr::with_dir(tempdir(), print(fakemake::make("all", ml, force = TRUE)))## Current target is: all.Rout.## Current target is: a1.Rout.## Current target is: b1.Rout.## Current target is: a2.Rout.## [1] "b1.Rout" "a1.Rout" "a2.Rout" "all.Rout"This is pointless here, but targets might be files down a directory tree like ‘log/roxygen.Rout’ when building R packages.
Target rule b1 dumps its output to b1.Rout:
cat(readLines(file.path(tempdir(), "b1.Rout")), sep = "\n")## [1] "b1"Suppose it would programmatically create the target:
i <- which(sapply(ml, "[[", "target") == "b1.Rout")
ml[[i]]["code"] <- paste(ml[[i]]["code"],
"cat('hello, world\n', file = \"b1.Rout\")",
"print(\"foobar\")",
sep = ";")
withr::with_dir(tempdir(), print(fakemake::make("b1.Rout", ml, force = TRUE)))## Current target is: b1.Rout.## [1] "b1.Rout"cat(readLines(file.path(tempdir(), "b1.Rout")), sep = "\n")## hello, wo[1] "foobar"You end up with a broken target file, so you need to add a sink:
ml[[i]]["sink"] <- "b1.txt"
withr::with_dir(tempdir(), print(fakemake::make("b1.Rout", ml, force = TRUE)))## Current target is: b1.Rout.## [1] "b1.Rout"Now you get what you wanted:
cat(readLines(file.path(tempdir(), "b1.Rout")), sep = "\n")## hello, worldcat(readLines(file.path(tempdir(), "b1.txt")), sep = "\n")## [1] "b1"
## [1] "foobar"Rule a1 has code
i <- which(sapply(ml, "[[", "target") == "a1.Rout")
ml[[i]]["code"]## $code
## [1] "print(\"a1\")"that prints “a1” into “a1.Rout”:
cat(readLines(file.path(tempdir(), "a1.Rout")), sep = "\n")## [1] "a1"If we remove that code and its output file and rerun
ml[[i]]["code"] <- NULL
withr::with_dir(tempdir(), print(fakemake::make("a1.Rout", ml, force = TRUE)))## Current target is: a1.Rout.## Current target is: b1.Rout.## [1] "b1.Rout" "a1.Rout"the file is still created (note that target rule b1 down the make chain is run since we did not set recursive = FALSE ) but empty:
file.size(file.path(tempdir(), "a1.Rout"))## [1] 0As you have seen, you can temporarily force a build. You may set a target to be .PHONY which forces it (but not its prerequisites) to be built:
ml[[i]][".PHONY"] <- TRUE
withr::with_dir(tempdir(), print(fakemake::make("a1.Rout", ml)))## Current target is: a1.Rout.## Current target is: b1.Rout.## [1] "a1.Rout"Powers, Shelley, Jerry Peek, Tim O’Reilly, and Mike Loudikes. 2002. Unix Power Tools. O’Reilly & Associates.
This is a nice example of what restrictive software policies are good for: you end up with a buggy imitation like fakemake instead of the well established original. You should not regulate software installations for programmers, unless you take away their interpreters/compilers.↩