giovedì 1 agosto 2013

Utilizzo dei subrepositories di Mercurial

Scrivo questa nota con l'intento di riassumere le informazioni, spesso contraddittorie e parziali, sull'argomento raccolte sulla rete. Il fine di tale strumento, o almeno una delle finalità principali, è quella di favorire, a chi già fa uso del DVCS in esame, il riutilizzo in più progetti di componenti già sviluppati in precedenza. Al tal fine,  nel seguito della nota, propongo un esempio concreto dei passi da seguire per integrare un subrepository, contenente uno o più moduli già implementati, in  un nuovo progetto sviluppato, ad esempio, con l'IDE di Microsoft, il Visual Studio 2012. Supponiamo che il subrepository in esame  si chiami XYZ_Core Project.
Il primo passo consiste nella creazione di una struttura di cartelle del tipo:
NEW Project
|_SRC
  1. Nella cartella SRC, creiamo una solution vuota di Visual Studio con il nome del progetto che stiamo creando, ovvero NEW Project.
    A questo punto, la struttura delle cartelle sarà:
    NEW Project
    |--
    SRC
    |----
    NEW Project
  2. Apriamo un prompt dei comandi,  spostiamoci nella sottocartella  _SRC\NEW Project e cloniamo il repository xyz_core-project
    $: hg clone https://bitbucket.org/***/xyz_core-project;
    Ottenuti i progetti del subrepository, non resta che aggiungerli alla nostra solution:
  3. Fatto ciò, torniamo nella cartella root del progetto, ed aggiungiamo il file .hgignore adatto alla versione di Visual Studio utilizzata, ed un nuovo file, denominato .hgsub strutturato come segue:
    _SRC/NEW Project/xyz_core-project=xyz_core-project
    [subpath]
    (https://(?:[^@]+@)?bitbucket\.org/[^/]+)(/[^/]+)/(.*) = \1/\3
    Il file appena aggiunto è quello che indica al nostro DVCS che è presente un subrepository. Spendiamo un attimo per capire il conenuto di tale file:
    - A sinistra del segno di uguaglianza, troviamo il percorso relativo alla root del progetto principale, nel quale intendiamo inserire il subrepository;
    - A destra dell'uguaglianza c'è il nome simbolico del subrepository.
    - Sotto la chiave [subpath] viene specificato, mediante una regular expression, il percorso dal quale ottenere il subrepository, e a destra la stringa che rimpiazzerà il nome simbolico di cui sopra (xyz_core-project). Per una descrizione più dettagliata, e sicuramente meno confusa, si rimanda alla pagina SubrepoRemappingPlan.
  4. A questo punto siamo pronti per consolidare la struttura del nuovo repository, ed a condividerla con il resto del mondo.
    - In primo luogo eseguiamo il commit del nostro repository
    $: hg commit -m "Messaggio di commit" --subrepos
    Notare l'opzione --subrepos che indica al DVCS di estendere il comando in modo ricorsivo ai sottoprogetti indicati da file .hgsub. Al termine del comando, nella root del progetto verrà generato il file .hgsubstate che d'ora in poi avrà il compito di tener traccia della versione del sottoprogetto collegata al nostr repository (Subrepositories).
  5. Non resta che consolidare sul nostro server la nuova struttura del progetto:
    $: hg push
NOTA: I comandi hg pull e hg incoming che ci consentono rispettivamente di aggiornare la copia locale del nostro repository, o più semplicemente di vedere quali e quante sono le differenze tra la copia locale e quella centralizzata, non hanno un'opzione che renda il comando ricorsivo (come l'opzione --subrepos vista per hg pull), il che implica che la sincronizzazione del subrepository con la relativa versione centralizzata è a carico dell'utente. In altre parole, ci si dovrà spostare nella cartella del sotto progetto, e da questa posizione lanciare i comandi

$: hg pull
e
$: hg update
Enjoy