Veritas Ep. 1: Tu primer proyecto con Gradle

Abstract

Hello my name is: Veritas

Veritas es una biblioteca de validación de datos que construiremos de manera incremental a lo largo del curso. Su objetivo es ofrecer una API clara y extensible para declarar reglas, componer validaciones y obtener resultados expresivos, facilitando su uso tanto en aplicaciones como en otras bibliotecas. Iremos viendo cómo lograr estos objetivos paso a paso.

Comenzar un proyecto desde cero puede sentirse abrumador, incluso aterrador. Muchas veces no sabemos por dónde empezar, tropezamos en el camino y nos enfrentamos a decisiones que parecen correctas en un momento, pero de las que luego podemos arrepentirnos.

Por eso, Veritas no es solo una biblioteca: es también una historia que contaremos juntos. Una historia que nos servirá de guía para recorrer el proceso completo de creación de una biblioteca desde cero.

Veritas es, en última instancia, una excusa para aprender haciendo: para experimentar, equivocarnos, corregir el rumbo y descubrir cómo se construyen bibliotecas sólidas y reutilizables en el mundo real.

Estructura inicial de proyectos del curso

Comencemos creando una organización básica para los proyectos del curso. Esta carpeta puede ser compartida entre otros proyectos; si decides no usarla, solo tendrás que adaptar las rutas en los comandos posteriores.

Desde la terminal de PowerShell

$dibs     = 'dibs'           # raíz de proyectos del curso
$scripts  = 'scripts'        # scripts de terminal
$path     = Join-Path $dibs $scripts

New-Item -ItemType Directory -Path $path -Force | Out-Null
# Alternativas:
# (New-Item -ItemType Directory -Path $path -Force) >$null
# $null = (New-Item -ItemType Directory -Path $path -Force)

$dibs     = 'dibs'           # raíz de proyectos del curso
$scripts  = 'scripts'        # scripts de terminal
$path     = Join-Path $dibs $scripts

New-Item -ItemType Directory -Path $path -Force | Out-Null
# Alternativas:
# (New-Item -ItemType Directory -Path $path -Force) >$null
# $null = (New-Item -ItemType Directory -Path $path -Force)

¿Qué acabamos de hacer?

Join-Path Join-Path : compone rutas de forma portable (evita problemas con separadores \ \ o / / ).
New-Item -ItemType Directory New-Item -ItemType Directory : crea la carpeta destino (y las intermedias si faltan).
- -Path $path -Path $path : ruta objetivo construida con Join-Path Join-Path .
- -Force -Force : permite repetir el comando sin error si la carpeta ya existe.
- | | es el operador de pipeline: envía la salida del comando de la izquierda como entrada al de la derecha. En | Out-Null | Out-Null esa salida se descarta para mantener la terminal limpia.
  Alternativas: (comando) >$null (comando) >$null o $null = (comando) $null = (comando) ; en este apunte preferimos la forma con | | por ser más explícita.

Desde la terminal de Bash/Zsh

DIBS="dibs"         # raíz de proyectos del curso
SCRIPTS="scripts"   # scripts de terminal
PATH_DIR="$DIBS/$SCRIPTS"

mkdir -p "$PATH_DIR"

DIBS="dibs"         # raíz de proyectos del curso
SCRIPTS="scripts"   # scripts de terminal
PATH_DIR="$DIBS/$SCRIPTS"

mkdir -p "$PATH_DIR"

¿Qué acabamos de hacer?

mkdir -p "$DIBS/$SCRIPTS" mkdir -p "$DIBS/$SCRIPTS" : crea la ruta completa si no existe y no falla si ya está creada.
"$DIBS/$SCRIPTS" "$DIBS/$SCRIPTS" : ruta destino donde guardaremos scripts compartidos del curso.

(Opcional) Integrar con Git

Si quieres versionar tu estructura desde el inicio, puedes crear el repositorio local y el remoto en GitLab de forma automatizada. Te sugiero ejecutar primero un ensayo con -WhatIf -WhatIf (PowerShell) o --dry-run --dry-run (Bash) para validar qué va a ocurrir.

Script de PowerShell (ensayo con -WhatIf)

scripts/ps1/New-GitLabRepository.ps1

#Requires -Version 7.0
[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
param(
    [ValidateNotNullOrEmpty()]
    [Parameter(Mandatory)]
    [string] $User,

    [ValidateNotNullOrEmpty()]
    [string] $RepositoryDirectory = $PWD.Path,

    [string] $RepositoryName,
    [string] $Prefix
)

$ErrorActionPreference = 'Stop'

# Normalizar ruta (soporta relativa) y validar que sea carpeta
$RepositoryDirectory = (Resolve-Path -LiteralPath $RepositoryDirectory -ErrorAction Stop).Path
$repoDirInfo = Get-Item -LiteralPath $RepositoryDirectory
if (-not $repoDirInfo.PSIsContainer) {
    throw "The path '$RepositoryDirectory' is not a directory."
}

# Derivar nombre/prefijo si faltan
if (-not $RepositoryName -or [string]::IsNullOrWhiteSpace($RepositoryName)) {
    $RepositoryName = $repoDirInfo.Name.ToLower()
}
if (-not $Prefix -and $repoDirInfo.Parent) {
    $Prefix = $repoDirInfo.Parent.Name.ToLower()
}

# Nombre final del proyecto remoto
$target = if ([string]::IsNullOrWhiteSpace($Prefix)) { $RepositoryName } else { "$Prefix-$RepositoryName" }

# Crear remoto en GitLab
if ($PSCmdlet.ShouldProcess($target, 'Create GitLab repository')) {
    Push-Location -LiteralPath $repoDirInfo.FullName
    try {
        git init
        glab repo create $target --public
        if ($LASTEXITCODE) { throw "glab exited with code $LASTEXITCODE." }
        git remote add origin "https://gitlab.com/$User/$target.git"
    }
    finally {
        Pop-Location
    }
}

#Requires -Version 7.0
[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
param(
    [ValidateNotNullOrEmpty()]
    [Parameter(Mandatory)]
    [string] $User,

    [ValidateNotNullOrEmpty()]
    [string] $RepositoryDirectory = $PWD.Path,

    [string] $RepositoryName,
    [string] $Prefix
)

$ErrorActionPreference = 'Stop'

# Normalizar ruta (soporta relativa) y validar que sea carpeta
$RepositoryDirectory = (Resolve-Path -LiteralPath $RepositoryDirectory -ErrorAction Stop).Path
$repoDirInfo = Get-Item -LiteralPath $RepositoryDirectory
if (-not $repoDirInfo.PSIsContainer) {
    throw "The path '$RepositoryDirectory' is not a directory."
}

# Derivar nombre/prefijo si faltan
if (-not $RepositoryName -or [string]::IsNullOrWhiteSpace($RepositoryName)) {
    $RepositoryName = $repoDirInfo.Name.ToLower()
}
if (-not $Prefix -and $repoDirInfo.Parent) {
    $Prefix = $repoDirInfo.Parent.Name.ToLower()
}

# Nombre final del proyecto remoto
$target = if ([string]::IsNullOrWhiteSpace($Prefix)) { $RepositoryName } else { "$Prefix-$RepositoryName" }

# Crear remoto en GitLab
if ($PSCmdlet.ShouldProcess($target, 'Create GitLab repository')) {
    Push-Location -LiteralPath $repoDirInfo.FullName
    try {
        git init
        glab repo create $target --public
        if ($LASTEXITCODE) { throw "glab exited with code $LASTEXITCODE." }
        git remote add origin "https://gitlab.com/$User/$target.git"
    }
    finally {
        Pop-Location
    }
}

¿Qué acabamos de hacer?

#Requires -Version 7.0 #Requires -Version 7.0 : asegura PowerShell 7+.
[CmdletBinding(SupportsShouldProcess, ConfirmImpact='Medium')] [CmdletBinding(SupportsShouldProcess, ConfirmImpact='Medium')] habilita -WhatIf -WhatIf y -Confirm -Confirm . Úsalo primero con -WhatIf -WhatIf .
$RepositoryDirectory = $PWD.Path $RepositoryDirectory = $PWD.Path + Resolve-Path -LiteralPath Resolve-Path -LiteralPath : acepta rutas relativas y las normaliza; luego se obtiene Get-Item Get-Item para validar que sea carpeta.
$RepositoryName $RepositoryName y $Prefix $Prefix se derivan del directorio si no los pasas; el nombre remoto final es $Prefix-$RepositoryName $Prefix-$RepositoryName (o solo el nombre si no hay prefijo).
Push-Location Push-Location y Pop-Location Pop-Location : cambian el directorio de trabajo temporalmente. try { ... } finally { ... } try { ... } finally { ... } asegura que siempre se regrese al directorio original.
glab repo create $target --public glab repo create $target --public : crea el proyecto remoto en GitLab de forma pública (cambia a --private --private si prefieres).
if ($LASTEXITCODE) { throw ... } if ($LASTEXITCODE) { throw ... } : si glab glab falla, se lanza una excepción para que el script termine con error.
git remote add origin ... git remote add origin ... : agrega el remoto llamado origin origin apuntando al repo recién creado.

Script de Bash/Zsh (ensayo con --dry-run)

scripts/sh/new-gitlab-repository.sh

#!/usr/bin/env bash
set -euo pipefail

USER=""
REPO_DIR="$(pwd)"
REPO_NAME=""
PREFIX=""
DRY_RUN=false

usage() {
  echo "Usage: $0 -u <user> [-d <directory>] [-n <repo_name>] [-p <prefix>] [--dry-run]"
  exit 1
}

while [[ $# -gt 0 ]]; do
  case $1 in
    -u|--user) USER="$2"; shift 2 ;;
    -d|--dir) REPO_DIR="$2"; shift 2 ;;
    -n|--name) REPO_NAME="$2"; shift 2 ;;
    -p|--prefix) PREFIX="$2"; shift 2 ;;
    --dry-run) DRY_RUN=true; shift ;;
    *) usage ;;
  esac
done

if [[ -z "$USER" ]]; then
  echo "Error: user is required"; usage
fi

if [[ ! -d "$REPO_DIR" ]]; then
  echo "Error: '$REPO_DIR' is not a directory"
  exit 1
fi

# Derivar nombre/prefijo
if [[ -z "$REPO_NAME" ]]; then
  REPO_NAME="$(basename "$REPO_DIR" | tr '[:upper:]' '[:lower:]')"
fi
if [[ -z "$PREFIX" ]]; then
  PARENT="$(dirname "$REPO_DIR")"
  PREFIX="$(basename "$PARENT" | tr '[:upper:]' '[:lower:]')"
fi

TARGET="$REPO_NAME"
if [[ -n "$PREFIX" ]]; then
  TARGET="$PREFIX-$REPO_NAME"
fi

echo "Repositorio remoto: $TARGET"

run() {
  if $DRY_RUN; then
    echo "[dry-run] $*"
  else
    eval "$@"
  fi
}

(
  cd "$REPO_DIR"
  run "git init"
  run "glab repo create $TARGET --public"
  run "git remote add origin https://gitlab.com/$USER/$TARGET.git"
)

#!/usr/bin/env bash
set -euo pipefail

USER=""
REPO_DIR="$(pwd)"
REPO_NAME=""
PREFIX=""
DRY_RUN=false

usage() {
  echo "Usage: $0 -u <user> [-d <directory>] [-n <repo_name>] [-p <prefix>] [--dry-run]"
  exit 1
}

while [[ $# -gt 0 ]]; do
  case $1 in
    -u|--user) USER="$2"; shift 2 ;;
    -d|--dir) REPO_DIR="$2"; shift 2 ;;
    -n|--name) REPO_NAME="$2"; shift 2 ;;
    -p|--prefix) PREFIX="$2"; shift 2 ;;
    --dry-run) DRY_RUN=true; shift ;;
    *) usage ;;
  esac
done

if [[ -z "$USER" ]]; then
  echo "Error: user is required"; usage
fi

if [[ ! -d "$REPO_DIR" ]]; then
  echo "Error: '$REPO_DIR' is not a directory"
  exit 1
fi

# Derivar nombre/prefijo
if [[ -z "$REPO_NAME" ]]; then
  REPO_NAME="$(basename "$REPO_DIR" | tr '[:upper:]' '[:lower:]')"
fi
if [[ -z "$PREFIX" ]]; then
  PARENT="$(dirname "$REPO_DIR")"
  PREFIX="$(basename "$PARENT" | tr '[:upper:]' '[:lower:]')"
fi

TARGET="$REPO_NAME"
if [[ -n "$PREFIX" ]]; then
  TARGET="$PREFIX-$REPO_NAME"
fi

echo "Repositorio remoto: $TARGET"

run() {
  if $DRY_RUN; then
    echo "[dry-run] $*"
  else
    eval "$@"
  fi
}

(
  cd "$REPO_DIR"
  run "git init"
  run "glab repo create $TARGET --public"
  run "git remote add origin https://gitlab.com/$USER/$TARGET.git"
)

¿Qué acabamos de hacer?

#!/usr/bin/env bash #!/usr/bin/env bash : indica al sistema que use Bash (o la shell compatible que encuentre en el PATH).
set -euo pipefail set -euo pipefail :
- -e -e termina el script si algún comando falla.
- -u -u termina si se usa una variable no definida.
- -o pipefail -o pipefail asegura que los fallos en pipelines no pasen desapercibidos.
Bloque usage() {} usage() {} : define la ayuda y parámetros válidos (-u, -d, -n, -p, --dry-run).
while [[ $# -gt 0 ]]; do case ... esac while [[ $# -gt 0 ]]; do case ... esac : $# $# representa el número de argumentos posicionales que recibió el script.
- Si el script se invoca como ./script.sh -u alice -d ./repo ./script.sh -u alice -d ./repo , entonces $# $# vale 4 (cada flag y cada valor cuentan).
- El bucle while [[ $# -gt 0 ]] while [[ $# -gt 0 ]] se repite mientras queden argumentos por procesar.
- Dentro, case $1 in ... esac case $1 in ... esac evalúa el primer argumento ( $1 $1 ), lo asigna a una variable y luego shift shift avanza, reduciendo $# $# en 1 (o en 2 si es flag con valor).
De esta forma se recorren y procesan todos los parámetros pasados al script.
Validación: si no se pasa --user --user se muestra error. También se valida que $REPO_DIR $REPO_DIR sea un directorio existente.
Derivación de nombres:
- basename basename obtiene el nombre de la carpeta actual como $REPO_NAME $REPO_NAME .
- dirname dirname y basename basename del padre dan $PREFIX $PREFIX .
- Ambos se transforman a minúsculas con tr '[:upper:]' '[:lower:]' tr '[:upper:]' '[:lower:]' .
El nombre final del repo es $PREFIX-$REPO_NAME $PREFIX-$REPO_NAME (o solo el nombre si no hay prefijo).
Se imprime "Repositorio remoto: $TARGET" "Repositorio remoto: $TARGET" para mostrar qué nombre tendrá en GitLab antes de ejecutar nada.
Función run() { } run() { } :
- Si está activo --dry-run --dry-run , solo imprime el comando.
- Si no, lo ejecuta realmente con eval eval . $@ $@ representa todos los argumentos pasados a la función.
Subshell ( cd "$REPO_DIR" ... ) ( cd "$REPO_DIR" ... ) : cambia de directorio solo dentro del bloque de paréntesis para no alterar la sesión actual.
Dentro del subshell:
- git init git init inicializa el repositorio local.
- glab repo create $TARGET --public glab repo create $TARGET --public crea el repositorio en GitLab (usa --private --private si quieres).
- git remote add origin https://gitlab.com/$USER/$TARGET.git git remote add origin https://gitlab.com/$USER/$TARGET.git conecta el repo local con el remoto.

Flujo sugerido (con ensayo primero)

Desde la terminal de PowerShell

Set-Location 'dibs'
$gitlabUser = '<TU-USUARIO>' # <- Reemplaza aquí
.\scripts\ps1\New-GitLabRepository.ps1 -User $gitlabUser -RepositoryDirectory .\scripts -WhatIf
.\scripts\ps1\New-GitLabRepository.ps1 -User $gitlabUser -RepositoryName index -Prefix dibs -WhatIf

Set-Location 'dibs'
$gitlabUser = '<TU-USUARIO>' # <- Reemplaza aquí
.\scripts\ps1\New-GitLabRepository.ps1 -User $gitlabUser -RepositoryDirectory .\scripts -WhatIf
.\scripts\ps1\New-GitLabRepository.ps1 -User $gitlabUser -RepositoryName index -Prefix dibs -WhatIf

¿Qué acabamos de hacer?

El flag -WhatIf -WhatIf simula la ejecución sin hacer nada. Si todo luce bien, repite los comandos sin -WhatIf -WhatIf .

Cuando se te pregunte elige no crear una carpeta local para el proyecto remoto (n), ya que el script ya se encarga de eso.

Desde la terminal de Bash/Zsh

cd dibs
GITLAB_USER="<TU-USUARIO>" # <- Reemplaza aquí
./scripts/sh/new-gitlab-repository.sh -u "$GITLAB_USER" -d ./scripts --dry-run
./scripts/sh/new-gitlab-repository.sh -u "$GITLAB_USER" -n index -p dibs --dry-run

cd dibs
GITLAB_USER="<TU-USUARIO>" # <- Reemplaza aquí
./scripts/sh/new-gitlab-repository.sh -u "$GITLAB_USER" -d ./scripts --dry-run
./scripts/sh/new-gitlab-repository.sh -u "$GITLAB_USER" -n index -p dibs --dry-run

¿Qué acabamos de hacer?

--dry-run --dry-run imprime los comandos en lugar de ejecutarlos. Si luce bien, repite sin --dry-run --dry-run .

.gitignore

Genera un .gitignore adecuado para cada repo; puede ayudarte: toptal.com/developers/gitignore.

Desde la terminal de PowerShell

# Commit y push del repo 'dibs/scripts', luego agregarlo como submódulo en 'dibs/index'
Push-Location '.\scripts'
git add .
git commit -m "chore(scripts): initial scaffolding and GitLab integration utilities"
git push -u origin main
Pop-Location
# Commit y push del repo 'dibs/index'
git submodule add "https://gitlab.com/$gitlabUser/dibs-scripts.git" scripts
git add .gitmodules scripts
git commit -m "chore(index): add scripts as submodule"
git push -u origin main

# Commit y push del repo 'dibs/scripts', luego agregarlo como submódulo en 'dibs/index'
Push-Location '.\scripts'
git add .
git commit -m "chore(scripts): initial scaffolding and GitLab integration utilities"
git push -u origin main
Pop-Location
# Commit y push del repo 'dibs/index'
git submodule add "https://gitlab.com/$gitlabUser/dibs-scripts.git" scripts
git add .gitmodules scripts
git commit -m "chore(index): add scripts as submodule"
git push -u origin main

¿Qué acabamos de hacer?

Primer bloque: versiona y sube el repo dibs/scripts.
Segundo bloque: añade dibs/scripts como submódulo en dibs/index y lo sube al remoto.

Desde la terminal de Bash/Zsh

# Commit y push del repo 'dibs/scripts', luego agregarlo como submódulo en 'dibs/index'
(
  cd scripts
  git add .
  git commit -m "chore(scripts): initial scaffolding and GitLab integration utilities"
  git push -u origin main
)

# Commit y push del repo 'dibs/index'
git submodule add "https://gitlab.com/$GITLAB_USER/dibs-scripts.git" scripts
git add .gitmodules scripts
git commit -m "chore(index): add scripts as submodule"
git push -u origin main

# Commit y push del repo 'dibs/scripts', luego agregarlo como submódulo en 'dibs/index'
(
  cd scripts
  git add .
  git commit -m "chore(scripts): initial scaffolding and GitLab integration utilities"
  git push -u origin main
)

# Commit y push del repo 'dibs/index'
git submodule add "https://gitlab.com/$GITLAB_USER/dibs-scripts.git" scripts
git add .gitmodules scripts
git commit -m "chore(index): add scripts as submodule"
git push -u origin main

¿Qué acabamos de hacer?

El bloque entre paréntesis crea un subshell que entra a scripts, hace commit inicial y lo sube a GitLab.
Luego, desde dibs/index, se añade el submódulo, actualiza .gitmodules y se sube todo al remoto.

Submódulos Git

Un submódulo es un repositorio independiente enlazado dentro de otro repositorio. Se usa cuando quieres mantener el historial y la evolución de un proyecto externo (o de otro repo tuyo) sin copiar su contenido. Así, el repo principal guarda solo una referencia fija a un commit del submódulo. Puedes actualizar esa referencia cuando quieras, pero los cambios en el submódulo se gestionan por separado.

Aprende más sobre submódulos en la documentación de Atlassian.

Inicializar un proyecto con Gradle

Crearemos un script mínimo para generar un esqueleto de proyecto donde tú elijas. La clave es normalizar la ruta (soporta relativas) y ejecutar gradle init en ese directorio. Recomiendo probar¹ con -WhatIf -WhatIf / --dry-run --dry-run antes.

`gradle init`

El comando gradle init crea la estructura inicial de un proyecto Gradle de manera guiada: puedes elegir tipo de proyecto (aplicación, biblioteca, etc.), DSL (Kotlin o Groovy) y nombre del proyecto, entre otros.

Inicializar proyecto Gradle

scripts/ps1/Initialize-GradleProject.ps1

#Requires -Version 7.0
[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string] $ProjectRoot,
    [string[]] $GradleOptions = @()
)

$ErrorActionPreference = 'Stop'

# Normalize the absolute path based on the current directory
$root = `
    if ([IO.Path]::IsPathRooted($ProjectRoot)) { $ProjectRoot } `
    else { Join-Path -Path $PWD.Path -ChildPath $ProjectRoot }

# Create directory if missing
if (-not (Test-Path -LiteralPath $root -PathType Container)) {
    if ($PSCmdlet.ShouldProcess($root, 'Create directory')) {
        New-Item -ItemType Directory -Path $root -Force | Out-Null
    }
}

# Run gradle init in the correct path
$gradle = (Get-Command gradle -ErrorAction Stop).Source
if ($PSCmdlet.ShouldProcess($root, 'gradle init')) {
    Write-Verbose "Running 'gradle init' in '$root'"
    & $gradle -p $root init @GradleOptions
    if ($LASTEXITCODE) { throw "Gradle exited with code $LASTEXITCODE." }
}

#Requires -Version 7.0
[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
param(
    [Parameter(Mandatory)]
    [ValidateNotNullOrEmpty()]
    [string] $ProjectRoot,
    [string[]] $GradleOptions = @()
)

$ErrorActionPreference = 'Stop'

# Normalize the absolute path based on the current directory
$root = `
    if ([IO.Path]::IsPathRooted($ProjectRoot)) { $ProjectRoot } `
    else { Join-Path -Path $PWD.Path -ChildPath $ProjectRoot }

# Create directory if missing
if (-not (Test-Path -LiteralPath $root -PathType Container)) {
    if ($PSCmdlet.ShouldProcess($root, 'Create directory')) {
        New-Item -ItemType Directory -Path $root -Force | Out-Null
    }
}

# Run gradle init in the correct path
$gradle = (Get-Command gradle -ErrorAction Stop).Source
if ($PSCmdlet.ShouldProcess($root, 'gradle init')) {
    Write-Verbose "Running 'gradle init' in '$root'"
    & $gradle -p $root init @GradleOptions
    if ($LASTEXITCODE) { throw "Gradle exited with code $LASTEXITCODE." }
}

¿Qué acabamos de hacer?

Esta explicación es más larga a propósito: es nuestro primer script y queremos revisar cada detalle con calma. Más adelante iremos omitiendo lo que ya hayamos aprendido.

#Requires -Version 7.0 #Requires -Version 7.0 : asegura que el script se ejecute con PowerShell 7+.²
[CmdletBinding(SupportsShouldProcess, ConfirmImpact='Medium')] [CmdletBinding(SupportsShouldProcess, ConfirmImpact='Medium')] : habilita ensayos seguros con -WhatIf -WhatIf (simula) y -Confirm -Confirm (pide confirmación).³
param(...) param(...) : define los parámetros de entrada. $ProjectRoot $ProjectRoot es la carpeta del proyecto (obligatoria). $GradleOptions $GradleOptions permite pasar banderas extra a gradle init gradle init .⁴
$ErrorActionPreference = 'Stop' $ErrorActionPreference = 'Stop' : si algo falla, se detiene inmediatamente.
Normaliza la ruta: convierte $ProjectRoot $ProjectRoot en absoluta con Join-Path Join-Path .⁵
Comprueba si la carpeta existe con Test-Path Test-Path y solo la crea si falta.⁶
$gradle = (Get-Command gradle -ErrorAction Stop).Source $gradle = (Get-Command gradle -ErrorAction Stop).Source : localiza el ejecutable de Gradle en el sistema.⁷
& $gradle -p $root init @GradleOptions & $gradle -p $root init @GradleOptions : ejecuta gradle init en la carpeta correcta.⁸
$LASTEXITCODE $LASTEXITCODE : verifica que Gradle terminó con éxito (0).⁹
Write-Verbose Write-Verbose muestra mensajes adicionales cuando corres con -Verbose -Verbose .¹⁰

Inicializar proyecto Gradle

scripts/sh/initialize-gradle-project.sh

#!/usr/bin/env bash
set -euo pipefail

PROJECT_ROOT="${1:-}"
shift || true
GRADLE_OPTS=( "$@" )

if [[ -z "${PROJECT_ROOT}" ]]; then
  echo "Usage: initialize-gradle-project.sh <project-root> [gradle options...]" >&2
  exit 1
fi

# Normalize to absolute path
case "${PROJECT_ROOT}" in
  /*|?:/*) ROOT="${PROJECT_ROOT}" ;;   # Unix abs or Windows drive abs (e.g., C:/)
  *)       ROOT="${PWD}/${PROJECT_ROOT}" ;;
esac

run () {
  if [[ "${DRY_RUN:-false}" == "true" ]]; then
    echo "[dry-run] $*"
  else
    eval "$@"
  fi
}

# Create directory if missing
if [[ ! -d "${ROOT}" ]]; then
  run "mkdir -p "${ROOT}""
fi

# Ensure gradle exists
if ! command -v gradle >/dev/null 2>&1; then
  echo "Gradle not found in PATH" >&2
  exit 127
fi

# Run gradle init in the correct path
run "gradle -p "${ROOT}" init ${GRADLE_OPTS[*]}"

#!/usr/bin/env bash
set -euo pipefail

PROJECT_ROOT="${1:-}"
shift || true
GRADLE_OPTS=( "$@" )

if [[ -z "${PROJECT_ROOT}" ]]; then
  echo "Usage: initialize-gradle-project.sh <project-root> [gradle options...]" >&2
  exit 1
fi

# Normalize to absolute path
case "${PROJECT_ROOT}" in
  /*|?:/*) ROOT="${PROJECT_ROOT}" ;;   # Unix abs or Windows drive abs (e.g., C:/)
  *)       ROOT="${PWD}/${PROJECT_ROOT}" ;;
esac

run () {
  if [[ "${DRY_RUN:-false}" == "true" ]]; then
    echo "[dry-run] $*"
  else
    eval "$@"
  fi
}

# Create directory if missing
if [[ ! -d "${ROOT}" ]]; then
  run "mkdir -p "${ROOT}""
fi

# Ensure gradle exists
if ! command -v gradle >/dev/null 2>&1; then
  echo "Gradle not found in PATH" >&2
  exit 127
fi

# Run gradle init in the correct path
run "gradle -p "${ROOT}" init ${GRADLE_OPTS[*]}"

¿Qué acabamos de hacer?

Esta explicación es más larga a propósito: es nuestro primer script y queremos revisar cada detalle con calma. Más adelante iremos omitiendo lo que ya hayamos aprendido.

#!/usr/bin/env bash #!/usr/bin/env bash : indica al sistema que use Bash (o la shell compatible que encuentre en el PATH).
set -euo pipefail set -euo pipefail refuerza la seguridad del script:
- -e -e : termina de inmediato si un comando falla.
- -u -u : falla si se usa una variable no definida.
- -o pipefail -o pipefail : en un pipeline, propaga el error del primer comando que falle en lugar de ocultarlo.
PROJECT_ROOT="${1:-}" PROJECT_ROOT="${1:-}" : guarda el primer argumento del script en la variable PROJECT_ROOT PROJECT_ROOT . $1 $1 representa el primer parámetro recibido al ejecutar el script. La sintaxis :- :- indica “usa este valor, o cadena vacía si no existe”. Así evitamos que la variable quede sin definir cuando no se pasa ningún argumento.
shift || true shift || true avanza los argumentos posicionales una posición (descarta $1 $1 , ya usado como PROJECT_ROOT PROJECT_ROOT ). El || true || true evita que el script termine con error si ya no hay más argumentos que desplazar.
GRADLE_OPTS=( "$@" ) GRADLE_OPTS=( "$@" ) guarda todos los argumentos restantes en un arreglo llamado GRADLE_OPTS GRADLE_OPTS . La sintaxis "$@" "$@" preserva cada argumento como un elemento separado (respetando espacios). Así, cualquier flag adicional se pasa intacta luego a gradle init gradle init .
if [[ -z "${PROJECT_ROOT}" ]]; then ... fi if [[ -z "${PROJECT_ROOT}" ]]; then ... fi valida que la variable PROJECT_ROOT PROJECT_ROOT no esté vacía. [[ ... ]] [[ ... ]] es la forma moderna de test en Bash, más robusta que [ ... ] [ ... ] . -z -z comprueba si la cadena está vacía. >&2 >&2 redirige el mensaje de error al flujo estándar de errores (stderr) en lugar de stdout, para distinguirlo de la salida normal.
Normaliza la ruta del proyecto usando $PWD $PWD . $PWD $PWD es una variable automática de Bash que siempre contiene la ruta del directorio actual desde donde ejecutas el script. Si PROJECT_ROOT PROJECT_ROOT es relativo, se antepone $PWD $PWD para convertirlo en absoluto y asegurar que el proyecto se cree en la carpeta correcta.
case ... in ... esac case ... in ... esac evalúa un valor contra varios patrones de texto. Es parecido a una cadena de if / else if que compara con expresiones regulares simples, no equivale a un pattern matching completo como en Scala o Python.
- /*|?:/*) /*|?:/*) : si el valor empieza con / (ruta absoluta en Unix) o con C:/ (ruta absoluta en Windows), se toma tal cual ( ROOT=${PROJECT_ROOT} ROOT=${PROJECT_ROOT} ).
- *) *) : el asterisco es un comodín que captura cualquier otro caso. Aquí tratamos la ruta como relativa y la volvemos absoluta anteponiendo $PWD $PWD (directorio actual en Bash).
;; ;; marca el final de cada rama dentro del bloque case.
Ensayo seguro: activa DRY_RUN=true DRY_RUN=true para ver qué haría el script sin ejecutar cambios reales.
Ejecuta gradle -p "$ROOT" init ${GRADLE_OPTS[*]} gradle -p "$ROOT" init ${GRADLE_OPTS[*]} en el directorio correcto sin moverte de carpeta.

Ejecutar con ensayo (-WhatIf)

scripts/ps1/Initialize-GradleProject.ps1

.scriptsps1Initialize-GradleProject.ps1 -ProjectRoot veritas -WhatIf

.scriptsps1Initialize-GradleProject.ps1 -ProjectRoot veritas -WhatIf

¿Qué acabamos de hacer?

...

scripts/sh/initialize-gradle-project.sh

...

...

¿Qué acabamos de hacer?

...

Al usar DirectoryInfo DirectoryInfo con rutas relativas, PowerShell puede resolverlas respecto a otra base (p. ej., el perfil). Con Join-Path -Path $PWD.Path -ChildPath ... Join-Path -Path $PWD.Path -ChildPath ... anclamos la ruta al directorio actual y evitamos crear el proyecto en otra ubicación.

El error original apareció al no usar Join-Path Join-Path :
```
What if: Performing the operation "Create Directory" on target "Destination: C:\Users\usuario\veritas".
What if: Performing the operation "gradle init" on target "C:\Users\usuario\veritas".
        
```
Gracias a -WhatIf -WhatIf / --dry-run --dry-run , detectamos al instante que apuntaba a C:\Users\... en vez de E:\...\Dibs. El ensayo reveló el fallo y la corrección segura fue normalizar la ruta antes de gradle init.
Volver
Puedes ajustar #Requires #Requires a otra versión, pero no garantizamos compatibilidad con PowerShell anterior. Volver
ConfirmImpact='Medium' ConfirmImpact='Medium' indica que la acción es importante y puede requerir confirmación en entornos sensibles. Volver
- [Parameter(Mandatory)] [Parameter(Mandatory)] marca $ProjectRoot $ProjectRoot como obligatorio.
- [ValidateNotNullOrEmpty()] [ValidateNotNullOrEmpty()] asegura que no sea nulo o vacío.
- [string] [string] : tipo de dato de la variable.
Ejemplo de uso: .\Initialize-GradleProject.ps1 -ProjectRoot foo -GradleOptions "--type kotlin-application","--dsl kotlin" .\Initialize-GradleProject.ps1 -ProjectRoot foo -GradleOptions "--type kotlin-application","--dsl kotlin" .
Volver
$PWD $PWD es una variable automática que guarda el directorio actual. Volver
-LiteralPath -LiteralPath evita que caracteres especiales se interpreten como comodines. -PathType Container -PathType Container asegura que sea carpeta, no archivo. $PSCmdlet.ShouldProcess $PSCmdlet.ShouldProcess permite ensayar acciones con -WhatIf -WhatIf o -Confirm -Confirm . Volver
Get-Command Get-Command encuentra el ejecutable real, aunque haya alias. -ErrorAction Stop -ErrorAction Stop corta si no se encuentra. Volver
& & es el call operator: ejecuta la ruta guardada en $gradle $gradle . -p -p fija el directorio del proyecto. @GradleOptions @GradleOptions usa splatting para expandir el arreglo como argumentos separados. Volver
Por convención, 0 significa éxito; cualquier otro código indica error. Volver
[CmdletBinding()] [CmdletBinding()] habilita parámetros comunes como -Verbose -Verbose y -Debug -Debug . Volver

Veritas Ep. 1: Tu primer proyecto con Gradle

Abstract

Hello my name is: Veritas

Estructura inicial de proyectos del curso

¿Qué acabamos de hacer?

¿Qué acabamos de hacer?

(Opcional) Integrar con Git

¿Qué acabamos de hacer?

¿Qué acabamos de hacer?

Flujo sugerido (con ensayo primero)

¿Qué acabamos de hacer?

¿Qué acabamos de hacer?

.gitignore

¿Qué acabamos de hacer?

¿Qué acabamos de hacer?

Submódulos Git

Inicializar un proyecto con Gradle

gradle init

¿Qué acabamos de hacer?

¿Qué acabamos de hacer?

¿Qué acabamos de hacer?

¿Qué acabamos de hacer?

Notas

`gradle init`