search

eudev-project / eudev

Repository for eudev development
GNU General Public License v2.0
525 stars 144 forks source link

Create file with configure and build instructions #205

Closed slicer69 closed 3 years ago

slicer69 commented 3 years ago

One of the challenges I faced when first checking out the eudev code was figuring out which dependencies and steps were required to compile and build the source code. This BUILD file includes step-by-step instructions to checkout, configure, build, and install eudev.

ArsenArsen commented 3 years ago

IMO, this should go in the README

slicer69 commented 3 years ago

I'm fine with moving these instructions to the README. I put them in a separate file as that was what was recommended when this document was discussed on the mailing list.

ArsenArsen commented 3 years ago

I wasn't aware of a currently active mailing list. Though, a much less verbose version in README would probably be good.

slicer69 commented 3 years ago

I'm not sure if it's a formally associated list, but the Debian Init Diversity team has been talking about efforts to keep eudev going. That's where I heard about this project and the effort to keep eudev going. http://www.chiark.greenend.org.uk/mailman/listinfo/debian-init-diversity

slicer69 commented 3 years ago

What I'll do is upload the README file with a short version of these instructions, with a comment to see the BUILD file for more details.

Kasijjuf commented 3 years ago

I'm inclined to follow GNU standard practice of putting build and installation instructions in a file called INSTALL as per https://www.gnu.org/prep/standards/html_node/Releases.html. This is the first file I look for in a tarball for compilation instructions. Following established filenaming conventions helps make software easier to use.

bbonev commented 3 years ago

Without strong preference, I am also inclined to use a separate file (text is best for this), and since the md have the option to link to it, make a link without any complications around it

ArsenArsen commented 3 years ago

I'm pretty sure even many GNU projects keep such instructions in a README. If it's complicated enough to warrant it's own file, it needs changing.

slicer69 commented 3 years ago

I'm inclined to follow GNU standard practice of putting build and installation instructions in a file called INSTALL as per https://www.gnu.org/prep/standards/html_node/Releases.html. This is the first file I look for in a tarball for compilation instructions. Following established filenaming conventions helps make software easier to use.

This was my original suggestion, but I was told that it should be called BUILD for this project since the instructions mostly focus on building the software rather than installing/configuring.

I'm pretty sure even many GNU projects keep such instructions in a README.

Usually no, most projects have a separate file for building, especially if they're from the pre-github era.

If it's complicated enough to warrant it's own file, it needs changing.

I disagree. The size of the instructions don't matter. What matters is providing clear documentation to make sure people know where to find what they need. Having a specific file is quicker and easier than dumping everything into one big README.

ArsenArsen commented 3 years ago

I disagree. The size of the instructions don't matter.

It's a symptom, not a problem unto itself. If it's truly that complex or fragile, it should be replaced. Many people fail to provide acceptable build systems, either by idealistically writing their own in pure make, or by shoving responsibility that should not be in the build system (such as obtaining dependencies) into it (which is particularly common with cmake), providing needless complications. The latter is an issue making me dread cmake more than even autotools. Ultimately, the build system currently here is temporary. I've already spent too many hours fighting with autotools for an extremely trivial purpose, which is to automatically build it.

Having a specific file is quicker and easier than dumping everything into one big README.

vim README<CR>/BUILDING<CR>

Bikeshedding this issue isn't a very productive use of time. Pick between a paragraph in the README and a paragraph in an external document, I've stated my preference previously, and we'll see it merged after checking it.

PS: could you reformat that apt install line to the column limit? The length stands out and makes it harder to read right now.

slicer69 commented 3 years ago

I'm closing this pull request and opening a new one since GitHub won't let me perform additional edits to the original. The new pull request has the same README.md as this, but has an edited BUILD file that properly formats the "apt install..." line.

I agree with Arsenarsen, this debate over the name/location of the documentation isn't productive. Between this thread and the mailing list discussion more time has been spent debating the location of the build documentation than I spent writing it. I feel it should be committed and, if people feel strongly about it, they can send a new pull request to tweak the wording/location. I have no issue with people adjusting the document once it's been pulled into the repo.