| Message ID | 20191026005159.98405-3-emilyshaffer@google.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | some clarifications to MyFirstContribution | expand |
Hi, Emily Shaffer wrote: > Indicate that the user needs some dependencies before the build will run > happily on their machine; this dependency list doesn't seem to be made > clear anywhere else in the project documentation. In theory, this info should be in INSTALL. I wouldn't be surprised if it's missing some info, though. [...] > --- a/Documentation/MyFirstContribution.txt > +++ b/Documentation/MyFirstContribution.txt > @@ -38,6 +38,30 @@ $ git clone https://github.com/git/git git > $ cd git > ---- > > +[[dependencies]] > +=== Installing Dependencies > + > +To build Git from source, you need to have a handful of dependencies installed > +on your system. For a hint of what's needed, you can take a look at > +`ci/install-dependencies.sh`. > + > +To install the dependencies needed for a basic build on Linux, run something > +like this (or replace `apt` with your distribution's package manager of choice): pedantic nit: s/or replace/replacing/ ("or" would mean rpm is an alternative to what came before, but "something like" in the phrase before has rpm already included) > + > +---- > +# apt install libssl-dev zlib1g-dev libcurl4-gnutls-dev libexpat1-dev Perhaps build-essential, too, in case they're using a system not set up for development. > +---- > + > +Make sure that your environment has everything you need by building your brand > +new clone of Git from the above step: > + > +---- > +$ make > +---- > + > +NOTE: The Git build is parallelizable. `-j#` is not included above but you can > +use it as you prefer, here and elsewhere. > + > [[identify-problem]] > === Identify Problem to Solve > > @@ -138,9 +162,6 @@ NOTE: When you are developing the Git project, it's preferred that you use the > `DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn > it off, but it's a good idea to mention the problem to the mailing list. > > -NOTE: The Git build is parallelizable. `-j#` is not included above but you can > -use it as you prefer, here and elsewhere. > - > Great, now your new command builds happily on its own. But nobody invokes it. > Let's change that. With whatever subset of the changes above make sense, Reviewed-by: Jonathan Nieder <jrnieder@gmail.com> Thanks.
Jonathan Nieder <jrnieder@gmail.com> writes: > Hi, > > Emily Shaffer wrote: > >> Indicate that the user needs some dependencies before the build will run >> happily on their machine; this dependency list doesn't seem to be made >> clear anywhere else in the project documentation. > > In theory, this info should be in INSTALL. I wouldn't be surprised if > it's missing some info, though. > > [...] >> --- a/Documentation/MyFirstContribution.txt >> +++ b/Documentation/MyFirstContribution.txt >> @@ -38,6 +38,30 @@ $ git clone https://github.com/git/git git >> $ cd git >> ---- >> >> +[[dependencies]] >> +=== Installing Dependencies >> + >> +To build Git from source, you need to have a handful of dependencies installed >> +on your system. For a hint of what's needed, you can take a look at >> +`ci/install-dependencies.sh`. >> + >> +To install the dependencies needed for a basic build on Linux, run something >> +like this (or replace `apt` with your distribution's package manager of choice): > > pedantic nit: s/or replace/replacing/ ("or" would mean rpm is an > alternative to what came before, but "something like" in the phrase > before has rpm already included) This section, as you hinted at the beginning, should be a single sentence, i.e. just "follow INSTALL". Any clarifications should be made as a patch to the INSTALL file. Thanks.
On Mon, Oct 28, 2019 at 10:27:25AM +0900, Junio C Hamano wrote: > Jonathan Nieder <jrnieder@gmail.com> writes: > > > Hi, > > > > Emily Shaffer wrote: > > > >> Indicate that the user needs some dependencies before the build will run > >> happily on their machine; this dependency list doesn't seem to be made > >> clear anywhere else in the project documentation. > > > > In theory, this info should be in INSTALL. I wouldn't be surprised if > > it's missing some info, though. > > > > [...] > >> --- a/Documentation/MyFirstContribution.txt > >> +++ b/Documentation/MyFirstContribution.txt > >> @@ -38,6 +38,30 @@ $ git clone https://github.com/git/git git > >> $ cd git > >> ---- > >> > >> +[[dependencies]] > >> +=== Installing Dependencies > >> + > >> +To build Git from source, you need to have a handful of dependencies installed > >> +on your system. For a hint of what's needed, you can take a look at > >> +`ci/install-dependencies.sh`. > >> + > >> +To install the dependencies needed for a basic build on Linux, run something > >> +like this (or replace `apt` with your distribution's package manager of choice): > > > > pedantic nit: s/or replace/replacing/ ("or" would mean rpm is an > > alternative to what came before, but "something like" in the phrase > > before has rpm already included) > > This section, as you hinted at the beginning, should be a single > sentence, i.e. just "follow INSTALL". Any clarifications should > be made as a patch to the INSTALL file. Thanks. I ended up with a little over one sentence; I don't like that a newbie following INSTALL file would end up with their locally-built Git installed (and they may only be interested in a one-off contribution, and never fetch again, or something) so I tried to highlight the dependencies portion of INSTALL: To build Git from source, you need to have a handful of dependencies installed on your system. For a hint of what's needed, you can take a look at `INSTALL`, paying close attention to the section about Git's dependencies on external programs and libraries. That document mentions a way to "test-drive" our freshly built Git without installing; that's the method we'll be using in this tutorial. Make sure that your environment has everything you need by building your brand new clone of Git from the above step: - Emily
diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index 12b7256454..b8ffeda07e 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -38,6 +38,30 @@ $ git clone https://github.com/git/git git $ cd git ---- +[[dependencies]] +=== Installing Dependencies + +To build Git from source, you need to have a handful of dependencies installed +on your system. For a hint of what's needed, you can take a look at +`ci/install-dependencies.sh`. + +To install the dependencies needed for a basic build on Linux, run something +like this (or replace `apt` with your distribution's package manager of choice): + +---- +# apt install libssl-dev zlib1g-dev libcurl4-gnutls-dev libexpat1-dev +---- + +Make sure that your environment has everything you need by building your brand +new clone of Git from the above step: + +---- +$ make +---- + +NOTE: The Git build is parallelizable. `-j#` is not included above but you can +use it as you prefer, here and elsewhere. + [[identify-problem]] === Identify Problem to Solve @@ -138,9 +162,6 @@ NOTE: When you are developing the Git project, it's preferred that you use the `DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn it off, but it's a good idea to mention the problem to the mailing list. -NOTE: The Git build is parallelizable. `-j#` is not included above but you can -use it as you prefer, here and elsewhere. - Great, now your new command builds happily on its own. But nobody invokes it. Let's change that.
Indicate that the user needs some dependencies before the build will run happily on their machine; this dependency list doesn't seem to be made clear anywhere else in the project documentation. Then, so the user can be certain any build failures are due to their code and not their environment, perform a build on a clean checkout of 'master'. Also, move the note about build parallelization up here, so that it appears next to the very first build invocation in the tutorial. Signed-off-by: Emily Shaffer <emilyshaffer@google.com> --- Documentation/MyFirstContribution.txt | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-)