From db80cf80e88d97f8c390433df6d38c47b19e0726 Mon Sep 17 00:00:00 2001 From: Marco Clemencic Date: Fri, 25 Nov 2016 13:22:54 +0100 Subject: [PATCH] updated LHCb development instructions --- lhcb-dev.md | 95 +++++++++++++++++++++++++++++------------------------ 1 file changed, 52 insertions(+), 43 deletions(-) diff --git a/lhcb-dev.md b/lhcb-dev.md index c9b8648..69fab84 100644 --- a/lhcb-dev.md +++ b/lhcb-dev.md @@ -8,15 +8,15 @@ minutes: 10 > ## Learning Objectives {.objectives} > * Learn the basics of how to work with and modify LHCb software packages -This lesson introduces you to two commands: +This lesson introduces you the commands: - `lb-dev` for setting up a new development environment - - `getpack` for downloading LHCb software packages + - `git lb-use` and `git lb-checkout` for downloading LHCb software packages If you want to make changes to a software package, you will need to set up a development environment. `lb-dev` is your friend here: ```bash -lb-dev --name DaVinciDev DaVinci v41r2 +lb-dev --name DaVinciDev DaVinci/v41r2 ``` The output should look similar to this: @@ -60,7 +60,7 @@ Follow those instructions and once you've compiled your software run inside the directory. This will (similar to `lb-run`) give you a new bash session with the right environment variables. Your new development environment won't be very useful without any software to modify and build. -So why not check out out one of the existing LHCb packages, which are stored in the LHCb SVN repository? +So why not check out one of the existing LHCb packages, which are stored in the [LHCb Git repositories](https://gitlab.cern.ch/lhcb)? Let's assume you have already used `lb-dev` to set up your development environment and you are currently inside it. In order to obtain the source code of the package you want to work on, use the [Git4LHCb](https://twiki.cern.ch/twiki/bin/view/LHCb/Git4LHCb) scripts. @@ -76,6 +76,20 @@ make configure Under the hood, `git lb-use` will add the [`Stripping`](https://gitlab.cern.ch/lhcb/Stripping) repository as a remote in git. `git lb-checkout` will then perform a partial checkout of the master branch of the Stripping repository, only adding the files under [`Phys/StrippingSelections`](https://gitlab.cern.ch/lhcb/Stripping/tree/master/Phys/StrippingSelections). +> ## Which project to use in `git lb-use`? {.callout} +> The project name to pass to `git lb-use` depends on the directories you want +> to check out and work on, and not on the project name you passed to `lb-dev`. +> Moreover you can call `git lb-use` several times for different remote +> projects in the same local project: +> +> ```bash +> lb-dev --name DaVinciDev DaVinci/v40r2 +> cd DaVinciDev +> git lb-use Analysis +> git lb-use Stripping +> git lb-use DaVinci +> ``` + You can now modify the `StrippingSelections` package and run `make purge && make` to build it with your changes. You can test your changes with the `./run` script. It works similar to `lb-run`, without the need to specify a package and version: @@ -83,26 +97,17 @@ It works similar to `lb-run`, without the need to specify a package and version: ./run gaudirun.py options.py ``` -> ## What if git asks for my password 1000 times? {.callout} -> `git` might ask you for your password several times. -> To avoid this, you can create a kerberos token with -> ``` -> kinit $USER@CERN.CH -> ``` -> You will have to enter your password once, and further password prompts will be skipped. - -If you just want to take a look at a source file, without checking it out, you can comfortably access the repository through two different web UIs. - - * [Trac](https://svnweb.cern.ch/trac/lhcb/) - * [SVNweb](http://svnweb.cern.ch/world/wsvn/lhcb) - -(which one to use? It is just a matter of taste, pick the one that looks nicest) +> ## What if `git` asks for my password? {.callout} +> Make sure you followed the [prerequisites](https://twiki.cern.ch/twiki/bin/view/LHCb/Git4LHCb#Prerequisites) +> section in the [Git4LHCb TWiki page](https://twiki.cern.ch/twiki/bin/view/LHCb/Git4LHCb). -To get an idea of how a certain component of the LHCb software works, you can access its doxygen documentation. -There is a page for each project, lists of projects can be found here: +If you just want to take a look at a source file, without checking it out, you can comfortably access the repository through +the [Gitlab web interface](https://gitlab.cern.ch/lhcb). - * [https://lhcb-release-area.web.cern.ch/LHCb-release-area/DOC/davinci/latest_doxygen/index.html](https://lhcb-release-area.web.cern.ch/LHCb-release-area/DOC/davinci/latest_doxygen/index.html). - * [http://lhcb-comp.web.cern.ch/lhcb-comp/](http://lhcb-comp.web.cern.ch/lhcb-comp/) +To get an idea of how a certain component of the LHCb software works, you can access the doxygen documentation. +One set of doxygen web pages is generated for several related projects, and is linked in all the +projects web sites, like https://cern.ch/LHCb-release-area/DOC/davinci/. +See also the the [LHCb Computing web page](http://cern.ch/lhcb-comp/) for a list of projects. Another useful tool available on lxplus machines is `Lbglimpse`. It allows you to search for a given string in the source code of LHCb software. ```bash @@ -110,27 +115,33 @@ Lbglimpse "PVRefitter" DaVinci v41r2 ``` It works with every LHCb project and released version. -If you have made changes that are supposed to be integrated into the official LHCb repositories, you can use `svn commit`. -But read the instructions in the SVN usage guidelines first. +If you have made changes that are supposed to be integrated into the official LHCb repositories, you can use `git lb-push`. +But read the instructions in the [TWiki page](https://twiki.cern.ch/twiki/bin/view/LHCb/Git4LHCb#Using_Git_for_LHCb_development) first. - * [SVNUsageGuidelines](https://twiki.cern.ch/twiki/bin/view/LHCb/SVNUsageGuidelines) +Depending on the project, you may be required to document your changes in the +release notes which are found in `doc/release.notes`. -Be advised that you should always communicate with the package maintainers before committing changes! -The release managers have to find the packages to include in a new release. Therefore make sure -to document your changes in the release notes which are found in `doc/release.notes`. -After that put your commit into the tag collector. +After the call to `git lb-push`, go to the project repository web page to +create a new merge request, for example https://gitlab.cern.ch/lhcb/Stripping/merge_requests/new. - * [Tag collector FAQ](https://twiki.cern.ch/twiki/bin/view/LHCb/FAQ/TagCollectorFAQ) - * [LHCb Tag Collector](https://lhcb-tag-collector.web.cern.ch/lhcb-tag-collector/index.html) - -(The login button is in the top right corner.) +> ## Quick link to create a merge request {.callout} +> When pushing to a branch in a project in Gitlab you will see a message like: +> +> ``` +> remote: +> remote: Create merge request for my-branch: +> remote: https://gitlab.cern.ch/lhcb/Stripping/merge_requests/new?merge_request%5Bsource_branch%5D=my-branch +> remote: +> ``` +> +> You can use the URL in the message to quickly create a merge request for the +> changes you just pushed. -It is advisable to test new developments on the so-called nightly builds. -They take everything which is committed in the head versions of all packages -and try to build the given project. -You can checkout this version by doing: +It is advisable to test new developments on the so-called [nightly builds](https://lhcb-nightlies.cern.ch). +They take build all the projects with all pending merge requests. +You can use a nightly build version of a project with: ```bash -lb-dev DaVinci HEAD --nightly lhcb-head +lb-dev --nightly lhcb-head DaVinci/HEAD ``` A more detailed description of the command is found here: @@ -141,10 +152,8 @@ Therefore the nightly tests are performed. They first try to build the full soft If that is successful, they run some reference jobs and compare the output of the new build with a reference file. The results of the nightly builds can be found here. -* [Nightly tests](https://buildlhcb.cern.ch/nightlies/) +* [Nightly builds summaries](https://lhcb-nightlies.cern.ch) If the aim of the commit was to change the ouput, e.g. because you increased the -track reconstruction efficiency by a factor of two, inform the release manager of the package -such that he can update the reference file. - - +track reconstruction efficiency by a factor of two, mention it in the merge request +description, such that the manager of the affected project can update the reference file.