#!/usr/bin/env bash # # Generation of icaruscode Doxygen documentation: # * fetches the latest Doxygen tag files for LArSoft and ROOT # (at most once per day) # * sets up the latest UPS version of `icaruscode` (needed for depedencies) # * checks out the latest tag of `icaruscode` `master` branch # * runs Doxygen (output is expected in the ${OutputDir} directory) # # ----------------------------------------------------- # Implementation note # ----------------------------------------------------- # # This script currently does not support generating documentation from multiple # repositories. To implement such support, a possible way is to have the user # specify a list of repositories including a main one (say, the first one) # which is where the Doxygen configuration file is. Then that configuration file # is processed to include as INPUT all the repositories, instead of just one. # Some additional work is needed to achieve that. # # # Changes # -------- # # 20200426 (petrillo@slac.stanford.edu) [v1.0] # first version in `icaruscode`; metadata version: 1 # 20200520 (petrillo@slac.stanford.edu) [v1.1] # using GitHub sources # 20201009 (petrillo@slac.stanford.edu) [v1.2] # support additional repositories; metadata version: 2 # 20210302 (petrillo@slac.stanford.edu) [v1.3] # support for non-`master` release branches (like in `sbnobj`); # in case of tagged target, use the versions from UPS for all repositories # # -- BEGIN -- boilerplate settings and library loading ------------------------- SCRIPTNAME="$(basename "$0")" SCRIPTDIR="$(dirname "$0")" declare LibraryToLoad for LibraryToLoad in 'settings.sh' 'experiment_settings.sh' 'utilities.sh' ; do source "${SCRIPTDIR%/}/${LibraryToLoad}" || exit $? done unset LibraryToLoad # -- END -- boilerplate settings and library loading --------------------------- # ------------------------------------------------------------------------------ SCRIPTVERSION="1.3" declare -ri MetadataVersion='2' # integral numbers please # ------------------------------------------------------------------------------ function printHelp() { cat <&2 res=$? [[ $res == 0 ]] && break echo " (failed)" done [[ -r "${CodeRepoPath}/.git" ]] || FATAL 1 "Could not download '${CodeRepoName}' code!" NewGITclone=1 fi NewGITclones["$CodeRepoName"]="$NewGITclone" local -i GITstashed local GIToldCommit if [[ "$RequestedCodeBranch" != 'HEAD' ]]; then local -r CodeBranch="${RequestedCodeBranch:-${ReleaseBranches[$CodeRepoName]:-${DefaultBranch}}}" if isFlagUnset NewGITclone ; then echo "Fetching updates for the existing GIT source tree of '${CodeRepoPath}'" git -C "$CodeRepoPath" fetch fi # remove everything that could bother our update; # git stash does not tell a script if a stash was created local -i nStashes="$(cd "$CodeRepoPath" && git stash list | wc -l)" git -C "$CodeRepoPath" stash save --quiet -- "${SCRIPTNAME} temporary for Doxygen generation - $(date)" LASTFATAL "Failed to save local changes in '${CodeRepoPath}'. Giving up." local -i nNewStashes="$(cd "$CodeRepoPath" && git stash list | wc -l)" if [[ "$nNewStashes" -gt "$nStashes" ]]; then echo "Changes in GIT repository temporary stashed." GITstashed+=( "$CodeRepoName" ) fi # also keep track of where we are GIToldCommit="$(cd "$CodeRepoPath" && git reflog -n 1 --format='format:%H')" local OldScriptChecksum="$(md5sum < "$0")" git -c 'advice.detachedHead=false' -C "$CodeRepoPath" checkout "$CodeBranch" local -i res=$? if [[ $res != 0 ]]; then RestoreGITrepository "$CodeRepoPath" "$GIToldCommit" "$GITstashed" if [[ -n "$RequestedCodeBranch" ]]; then FATAL "$res" "Failed to check out branch '${CodeBranch}' of GIT repository ${CodeRepoPath}." else echo "Failed to check out branch '${CodeBranch}' of GIT repository ${CodeRepoPath}." fi fi if [[ -n "$CodeBranch" ]] && ! hasGITtag "$CodeBranch" ; then echo "Updating the GIT branch..." git -C "$CodeRepoPath" rebase if [[ $res != 0 ]]; then RestoreGITrepository "$CodeRepoPath" "$GIToldCommit" "$GITstashed" echo "Failed to update (rebase) branch '${CodeBranch}' of GIT repository ${CodeRepoPath}." fi fi local GITnewCommit="$(cd "$CodeRepoPath" && git reflog -n 1 --format='format:%H')" [[ "$GITnewCommit" == "$GIToldCommit" ]] && unset GIToldCommit # no change, no need to track local NewScriptChecksum="$(md5sum < "$0")" if [[ "$OldScriptChecksum" != "$NewScriptChecksum" ]]; then FATAL 1 "The attempt to update the repository '${CodeRepoPath}' on the fly caused a change in this script ('${SCRIPTNAME}'). Please update the repository manually and try again." RestoreGITrepository "$CodeRepoPath" "$GIToldCommit" "$GITstashed" fi fi GIToldCommits["$CodeRepoName"]="$GIToldCommit" GITstashedRepos["$CodeRepoName"]="$GITstashed" } # PrepareRepository() function RestoreAllRepositories() { # restore the status of the repositories from stored information local CodeRepoName for CodeRepoName in "${CodeRepoNames[@]}" ; do RestoreGITrepository "${CodeRepoPaths[$CodeRepoName]}" "${GIToldCommits[$CodeRepoName]}" "${GITstashedRepos[$CodeRepoName]:-0}" done } # RestoreAllRepositories() function CheckOutSources() { # # find a Doxygen configuration file # local -r ExperimentName="$1" shift local RepoNames=( "$@" ) [[ -z "${RepoNames[0]}" ]] && RepoNames[0]="$(ExperimentCodeProduct "$ExperimentName" )" local ExperimentCodeName="${RepoNames[0]}" # in the future this constraint can be relaxed: local ExperimentCodeRepoPath="$ExperimentCodeName" local -r RequestedCodeBranch="$RequestedExperimentCodeBranch" # all the same branch, just because of the simpler interface local RequestedRepoVersion for CodeRepoName in "${RepoNames[@]}" ; do if [[ "$CodeRepoName" != "$ExperimentCodeName" ]]; then RequestedRepoVersion="$(UPSversion "$CodeRepoName")" else false # trigger the next conditio fi [[ $? == 0 ]] || RequestedRepoVersion="$RequestedCodeBranch" echo " === preparing repository '${CodeRepoName}' (${RequestedRepoVersion}) === " PrepareRepository "$CodeRepoName" "$RequestedRepoVersion" done echo " === all repositories prepared === " local -r ExperimentCodeVersion="$(cd "$ExperimentCodeRepoPath" && git describe --abbrev=0)" # use as tag # special: if no branch was requested in particular, we move to the tagged version of it if [[ -z "$RequestedCodeBranch" ]]; then for CodeRepoName in "${RepoNames[@]}" ; do echo " === Picking tag ${ExperimentCodeVersion} for ${CodeRepoName} ===" local CodeRepoPath="${CodeRepoPaths[$CodeRepoName]}" git -C "$CodeRepoPath" checkout "$ExperimentCodeVersion" || echo "${CodeRepoName} does not have tag '${ExperimentCodeVersion}', we'll use the current branch ($(git -C "$CodeRepoPath" describe))." done echo " === tag ${ExperimentCodeVersion} selection completed ===" fi GitDescription="$(cd "$ExperimentCodeRepoPath" && git describe 2> /dev/null)" [[ $? == 0 ]] && echo "Repository status: ${GitDescription}" return 0 } # CheckOutSources() ################################################################################ function RunDoxygen() { # # find a Doxygen configuration file # local -r ExperimentName="$1" shift local -a AdditionalRepositories=( "$@" ) local ExperimentCodeName="$(ExperimentCodeProduct "$ExperimentName" )" CodeRepoNames=( "$ExperimentCodeName" "${AdditionalRepositories[@]}" ) CheckOutSources "$ExperimentName" "${CodeRepoNames[@]}" local MasterDoxyfile # search for a Doxyfile in the current directory first MasterDoxyfile="$(FindDoxyfile "$ExperimentName" "$(pwd)" )" LASTFATAL "Can't find a doxygen configuration file for '${ExperimentName}'" local DateTag="$(date '+%Y%m%d')" local DoxygenLog="${LogDir%/}/$(basename "${MasterDoxyfile%.doxy*}")-${DateTag}.log" # in the future this constraint can be relaxed: local ExperimentCodeRepoPath="${CodeRepoPaths[$ExperimentCodeName]}" local -r ExperimentCodeVersion="$(cd "$ExperimentCodeRepoPath" && git describe --abbrev=0)" # use as tag mkdir -p "$LogDir" local -r Doxyfile="${TMPDIR:-/tmp}/${ExperimentCodeName}-${ExperimentCodeVersion}.doxy" echo "Creating Doxygen configuration from '${MasterDoxyfile}'..." PrepareDoxyfile "$MasterDoxyfile" "$Doxyfile" cat <" "$DoxygenLog" ) echo "${Cmd[@]}" eval "${Cmd[@]}" local -i ExitCode=$? if [[ -d "$ConfiguredOutputDir" ]]; then mv "$Doxyfile" "$ConfiguredOutputDir" && echo "Doxygen configuration copied into '${ConfiguredOutputDir}'." fi # restore the status of the repository RestoreAllRepositories if [[ -d "$ConfiguredOutputDir" ]]; then mkdir -p "$(dirname "$MetadataFile")" cat < "$MetadataFile" MetadataVersion = '${MetadataVersion}' Experiment = '${ExperimentName}' Date = '$(date)' Host = '$(hostname)' User = '$(whoami)' Configuration = '${MasterDoxyfile}' ExperimentCode = '${ExperimentCodeName}' CodeVersion = '${ExperimentCodeVersion:-"n/a"}' GITreference = '${GitDescription:-"n/a"}' WordDirectory = '$(pwd)' CommandLine = '${Cmd[@]}' DoxygenPath = '${doxygen}' DoxygenVersion = '$($doxygen --version)' LogFile = '${DoxygenLog}' ExitCode = '${ExitCode}' EOM ### END metadata version 1 ### BEGIN metadata version 2: cat <> "$MetadataFile" AdditionalRepos = ( ${AdditionalRepositories[@]} ) EOM ### END metadata version 2 fi cat <