New developers not familiar with open source tools seem to struggle to build Geany simply, add a section near the top of hacking with the simple "get you started" process. You can view, comment on, or merge this pull request online at:
https://github.com/geany/geany/pull/1690
-- Commit Summary --
* Add simplest development build process to HACKING
-- File Changes --
M HACKING (18)
-- Patch Links --
https://github.com/geany/geany/pull/1690.patch https://github.com/geany/geany/pull/1690.diff
Note: I don't have docutils on this machine, and as I'm writing an Asciidoc implementation my ReSt is probably dodgy. So needs checking
This might make more sense as a wiki article rather than an official recommendation.
It has a couple things that aren't such good ideas like in-tree builds, using `autogen.sh` in place of `configure` (even if it forwards the arguments, it's not a great idea, especially after the first time, and is likely to confuse people), and installing into the directory where the source directory is might cause confusion (think if they use `/home/projects` as the prefix, their projects directory will be filled with a bunch of install artifacts).
This might make more sense as a wiki article rather than an official recommendation.
Nobody reads the wiki unless directed to, it has turned out to essentially be a waste of server space, but it was worth trying.
It has a couple things that aren't such good ideas like in-tree builds,
Agree that there are good reasons that experienced developers don't want in-tree builds, but they work and Geany should not be one of those arrogant projects where you need to understand all the details of the tooling before you are allowed to touch the code. Coding in C with obsolete tools is already enough of a backwater that few want to do it, so we should show how to make it easy or stop complaining about lack of contributors. `</rant>`
This is a _simple_ build with _minimal_ steps, not a perfect one, and not intended to detail use of the tools.
using autogen.sh in place of configure
Well, its for a first build post git clone, so it has to be `autogen.sh` and I doubt people using this are going to be re-configuring often, so it doesn't hurt to use `autogen.sh` again in that rare case, again its not about teaching the tools but getting people started.
installing into the directory where the source directory is might cause confusion (think if they use /home/projects as the prefix, their projects directory will be filled with a bunch of install artifacts).
The very first thing it says is create a __new__ directory and put the source in there, maybe it needs emphasising, clearly you missed it :grin:
Nobody reads the wiki unless directed to, it has turned out to essentially be a waste of server space, but it was worth trying.
I don't know about that, it's frequently used/updated and indexed by Google.
This is a simple build with minimal steps, not a perfect one, and not intended to detail use of the tools.
IMO, this kind of documentation (for hackers) should set them up with a good foundation for actually hacking on Geany, not just how to make a one-off build, that is something more likely to be useful to regular users who need to build from source for whatever reason.
As above, if the instructions are to set the user up for how to properly hack on Geany, they will be reconfiguring fairly often, at least each time changes to the build system are pulled-in. Using autogen.sh also doesn't allow for out-of-tree builds, which is what we should be promoting if they actually want to get setup for doing real development.
The very first thing it says is create a new directory and put the source in there, maybe it needs emphasising, clearly you missed it
I didn't miss it, but I was really confused on first read. IMO, it's better to put everything under a separate working directory for Geany hackage, and separate out source from build from install, etc.
@codebrainz well, propose alternative text. If the recipe is short and simple then certainly setting people on the right path is good, but if it makes life harder for a first timer, then they will be a no-timer.
IMO, it would be better as more verbatim text explaining what each command is doing and why, rather than some magic incantation people blindly poke into the terminal, but I'm not sure HACKING is the appropriate place for that (hence the suggestion for a wiki page).
Without more verbatim explanations, I would personally recommend something more like this:
```bash export GEANY_DEV=$HOME/geany-dev
# one-time setup mkdir -p $GEANY_DEV/build $GEANY_DEV/prefix cd $GEANY_DEV git clone https://github.com/geany/geany.git source cd source NOCONFIGURE=1 ./autogen.sh
# configuring the build and when updating from Git cd $GEANY_DEV/build ../source/configure --prefix=$GEANY_DEV/prefix
# each rebuild/install/test make install
# running with a local config directory $GEANY_DEV/prefix/bin/geany -c $GEANY_DEV/config ```
Which results in a much more friendly directory structure like:
``` $HOME/geany-dev ├── build │ ├── ...build artifacts... ├── config │ ├── ...local config... ├── prefix │ ├── ...install artifacts... └── source ├── ...source tree... ```
Seems a good start, bung 'er in a PR.
Since its all in a new directory `geany_dev` not sure it needs `prefix` dir, its just another path to type, but thats a detail we can discuss on the PR.
@codebrainz pushed 1 commit.
0c4916a Flesh-out new HACKING docs
I added a longer section to the HACKING file, explaining stuff in more detail. Feel free to revert/revise/rebase/etc.
Tested locally each command and the restructured text rendering looks OK.
codebrainz commented on this pull request.
+so if you've change the source code, take heed of the warning/error
+messages reported here. + +If you have multiple CPUs/cores you can pass the `-j` option to `make` +to have it spin up the specified number of concurrent processes where +possible to complete the compilation and linking stages in less time. +Geany's build system is incremental, so after you hack on the code and +want to rebuild, you can run `make` again and only the needed files +will be built, which makes it much faster than the initial build. + +Once Geany is built, we want to install it into the provided `--prefix` +to test it, like this:: + + $ make install + +In fact, the `make install` rule will necessary run the complete build,
*necessarily
codebrainz commented on this pull request.
+`prefix/install_1`. This is where this build of Geany will be installed
+later, as opposed to the default directory (usually `/usr/local`, which +requires root permissions). The reason it's called `install_1` is +simply to highlight that you may want to have several concurrent +development installs without them interfering with each other. You +might name another install `install_2`, for example. The actual path is +completely arbitrary. + +With the build system configured, we're ready to compile and link Geany +into an executable program:: + + $ make + +This usually takes a few minutes, depending on the speed of your +system. This step is where you'll get all of your compilation errors +so if you've change the source code, take heed of the warning/error
*changed
codebrainz commented on this pull request.
+completely arbitrary.
+ +With the build system configured, we're ready to compile and link Geany +into an executable program:: + + $ make + +This usually takes a few minutes, depending on the speed of your +system. This step is where you'll get all of your compilation errors +so if you've change the source code, take heed of the warning/error +messages reported here. + +If you have multiple CPUs/cores you can pass the `-j` option to `make` +to have it spin up the specified number of concurrent processes where +possible to complete the compilation and linking stages in less time. +Geany's build system is incremental, so after you hack on the code and
*is _also_ incremental
codebrainz commented on this pull request.
+With the build system configured, we're ready to compile and link Geany
+into an executable program:: + + $ make + +This usually takes a few minutes, depending on the speed of your +system. This step is where you'll get all of your compilation errors +so if you've change the source code, take heed of the warning/error +messages reported here. + +If you have multiple CPUs/cores you can pass the `-j` option to `make` +to have it spin up the specified number of concurrent processes where +possible to complete the compilation and linking stages in less time. +Geany's build system is incremental, so after you hack on the code and +want to rebuild, you can run `make` again and only the needed files +will be built, which makes it much faster than the initial build.
*will be _re-built_
codebrainz commented on this pull request.
+work from a new config directory.
+ +Now you're ready to start hacking away on Geany. If you have an +explicit change in mind and plan to propose it for inclusion into Geany +proper, it's always best to create a Git branch to keep the changes +isolated from everything else:: + + $ git checkout -b fix-some-bug + +Now you can make changes to Geany's source and commit them to this +branch, and always get back to a clean Geany checkout by switching back +to the master branch like this:: + + $ git checkout master + +Whenever you've made changes to the source in some branch and want to
*sources
codebrainz commented on this pull request.
+ $ make + +This usually takes a few minutes, depending on the speed of your +system. This step is where you'll get all of your compilation errors +so if you've change the source code, take heed of the warning/error +messages reported here. + +If you have multiple CPUs/cores you can pass the `-j` option to `make` +to have it spin up the specified number of concurrent processes where +possible to complete the compilation and linking stages in less time. +Geany's build system is incremental, so after you hack on the code and +want to rebuild, you can run `make` again and only the needed files +will be built, which makes it much faster than the initial build. + +Once Geany is built, we want to install it into the provided `--prefix`
*into the directory specified for the `--prefix` option on the `configure` script above
@codebrainz pushed 1 commit.
ea5d32a Fix some grammar and spelling errors
I stumbled back upon this looking for something else, should it be merged?
IMHO, no, its no longer the simplest, which was the point of my original, its now TL;DR, but I don't care either way.
The changes certainly no longer reflect the title of the PR, but it still seems like useful information.
github-comments@lists.geany.org