We used to have a page in quick-docs titled "Installing software from source code". It was in quick-docs because it was converted as one of the most visited pages on the Wiki when we migrated these docs from there to Antora and docs.fp.o; this means it's information people look for often. However, the old quick-doc wasn't very good as was pointed out in #101, so we removed it (#108) to avoid confusing people.
It would be really nice if someone could put together a better, more thought-out version with a similar focus. You can check out any commit on master before #108 was merged (such as 53a437aac6b3610d5b011df47f9dd2f84eaa2cf1) to see what it originally looked like, if you want inspiration.
53a437aac6b3610d5b011df47f9dd2f84eaa2cf1
Metadata Update from @jflory7: - Issue priority set to: waiting on assignee - Issue tagged with: good first issue, help wanted, new change
I’m available to redo this documentation.
@ramin -- Awesome! Could you open a PR and we'll review and merge it please? Assigning to you now!
Metadata Update from @ankursinha: - Issue assigned to ramin
Metadata Update from @ankursinha: - Issue untagged with: help wanted
@ankursinha sure. I’ll get to it tomorrow when I get back to my office.
@ankursinha so I'm ready to get started, however, I'm really new to open source and would greatly appreciate if you would guide me in starting this project, how do I make the PR? what format should I be doing (ASCIIDOCS?)? I do apologize for my slowness. Also, where can I get the original files from so I know what I should be doing?
@ramin this should help you get started: https://pagure.io/fedora-docs/quick-docs/blob/master/f/README.md
I generally just read a few other source files---that gives you a good handle on the syntax etc. A good editor like vim/emacs/atom etc. will also highlight your syntax for you to make it easier to write.
The original files are all in this repo. When you've forked it, and then cloned your fork, you will have them all.
How experienced are you with building software from source? This topic does require some understanding of the process and the various "build projects": autotools/cmake/meson and so on. Do you have a good handle on those?
@ankursinha Thanks for the resources! And just to make sure I fork fedora-docs/quick-docs right? To answer your question, I have experience with cmake, and make utilities, to be honest, I haven't heard of meson, but I do compile from source both for myself, and to deploy my programs. :smile:
And just to make sure I fork fedora-docs/quick-docs right?
Yep, you got it! :thumbsup:
@jflory7 Thanks mate :)
For a final confirmation before I start after I fork the repo, I create a new branch (i.e. labelled "111-updating-install-from-source") and commit any of my new files into that and then open a PR and SOMEONE ELSE will integrate it with the whole repo? Or should I integrate the new page for installing from source into the repo and commit the whole thing to my new branch and open a PR?
Also, I'm having a hard time finding the previous page mentioned in the description? My apologies for my wild questionings 😅
cheers
@ramin The whole workflow goes like this:
ssh
https
origin
git remote add upstream https://pagure.io/fedora-docs/quick-docs.git
upstream
master
git push
git pull upstream master && git push origin master
Oh and regarding the previous page: the sequence of letters and numbers is a commit hash. When you have the repository cloned locally, you can use git checkout 53a437aac6b3610d5b011df47f9dd2f84eaa2cf1 to basically go back in history to see how the repository looked at that point of time. Once you run the command, you can build everything like normally (run ./build.sh && ./preview.sh and open the link displayed on the command line in your browser), and find the "Installing software from source" in the site menu, and then you'll see how it looked back then before we removed it.
git checkout 53a437aac6b3610d5b011df47f9dd2f84eaa2cf1
./build.sh && ./preview.sh
Don't forgeto to check out the latest commit on master again before you start making changes: git checkout master. Otherwise you'll be making changes against an old version of the repo and you'll run into a really nasty merge conflict.
git checkout master
@pbokoc Thank you for the very comprehensive guide, especially your last post which I had trouble understanding how to go to a particular commit based on the commit hash. Thanks mate! I have started doing the introductory sections on various build methods and terminology. I hope I can get a draft version finished by the end of the week. :smile:
I have almost completed the document, with only minor grammar and technical error checking to remain. But there seems to be an issue! When I build the repo an HTML gets generated for my new page, however, if I run preview.sh and navigate to the side menu, I cannot find my page on the list. i.e. Usage and customization > cannot find my page! I have added an xref to my page in the nav.adoc, but still no luck. Am I doing something wrong?
preview.sh
@pbokoc @ankursinha Is this something I can take over or work on?
Sure! @ramin : sorry---we seemed to have missed your message here for 3 years... were you able to get the previeww running? Would you have a version in a branch somewhere that @mmccabe4 could perhaps continue working on (instead of starting from scratch)?
@ankursinha Thank you if we do not receive any response, where can I locate the source code to begin working on this if we do not have a base? I want to make sure terminal commands are still proper. Additionally, would you like this from scratch or should I create a proper document just including all of the partials?
I see @ramin 's branch here with some work:
https://pagure.io/fork/ramin/fedora-docs/quick-docs/tree/111-better-installing-from-source
with 20 commits there that we don't have yet. I guess you could start from there if you wish?
https://pagure.io/fork/ramin/fedora-docs/quick-docs/commits/111-better-installing-from-source
@mmccabe4 , any progress here? Do you need help finishing up the docs @ramin had started to work on?
I took a quick look at the text. It seems to me to be largely elaborated and finished. In terms of content, I can't evaluate this conclusively. My last 'installation from source' was at least a decade ago.
I tend to accept the text as it is and look for a reviewer. Alternatively, to publish it and add an editor's note that a reviewer is still needed.
It would be too bad to waste the work that has been done, just because no one responded to his question for 3 years.
Comments / concerns about this?
Agreed docs meeting 2022-12-28: AGREED: We publish the work or ramin issue #111 (pboy, 19:51:55)
pboy takes over the task of doing the transfer.
Metadata Update from @pboy: - Issue untagged with: good first issue, new change - Issue assigned to pboy (was: ramin) - Issue priority set to: None (was: waiting on assignee)
@pboy Like 153, I put the article text on the left, which you can use for searching where the error is in the document. I put the problem in the brackets. Thanks.
give step by step instructions [should step by step be hyphenated]
in many diiferent ways [typo]
Make sure to read documentations to determine [plural]
way possible to do so. I.e. often you can find [i.e. seems incorrect]
your package manager I.e. dnf and yum and then [i.e.]
rare to stumble upon a software which requires to be installed from source [no need for 'a']
which requires to be installed from source [ is required ?]
However it used to be [comma after However]
Software limitaions, such as dependency issues [typo]
which reads the makefile and runs appropriate [should makefile be capitalized]
This file is responsible to ensure compatability [typo compatability]
Here we use package [comma after Here and "use a package"]
but we shall use software and program interchangebly in the contex of this document. Note that outside our contex a package [typos]
Also, often prgorams require [typo]
Many programs often require other programs to work, for such programs [period after work]
depend on others to provide them with the neccesary tools. [necessary typo]
It is often the case where newer software have compatability issues [should be has]
dependant software get installed on a machine running [gets installed]
f you have a similar issue such as the python compatability issue [typo compatability]
ALWAYS check for updates, the linux kernel [should linux be capitalized]
Fedora’s pakage managment system [2 typos]
by fedora’s package management system [consistent capitalization for fedora]
Since most software are composed [is composed]
and furtheremore it contains it’s assests such [several typos, apostrophe]
as the image used for it’s icon [apostrophe]
archiving system, it store related [it stores]
however such method is highly [add comma, and "a method"]
any dependencies that are neccessary [typo necessary]
configure file ensures for compatability [typo]
can pass them as a paramerter to [typo]
and want to build specific for that architecture [specifically]
Therefore it is neccesary that we dive [typo]
Full costomization can be achieved [typo]
environment variables, below we give an [new sentence with below]
ignore them, for more detailed information [new sentence for]
after a softwares compilation [after software ?]
acomplishes a lot of tasks [typo accomplishes]
which was extracted, are compiled into multiple object [is compiled]
These are the program itself, at this stage [grammar]
more detailed can be found here [detail typo]
some applications at system wide scope [hypenate system-wide ?]
bash returned and error [an error?]
To install a software, or simply put, to move the compiled executable into it’s proper directory [grammar]
make install is a simple comman [typo command]
but neatly organizes [it neatly]
and clean up it’s temporaries all with one command [apostrophe]
the ./ prefix simply tells [Capitalize the ?]
change your curent working directory [Capitalize change]
commands, in this document we [new sentence]
software, keep in mind however compiling source code, may take time dependeing [grammar and typos]
and a software was in early release [grammar]
problem arises due to compatability [typo]
Often installing in an unsuall location [typo unusual]
Although there is no definite solutions [are no]
@pboy and @anthonymcglone can someone verify the next steps here? It looks like:
main
@anthonymcglone are you going to edit the installing-from-source.adoc file, or does that still need to be done? If you're going to work on it I'll look for something else, but if not I can work on this.
installing-from-source.adoc
It's been a few years, but I've installed enough software with make, make install that I should be able to do a high-level technical review while updating the content.
make, make install
@alanbowman you're more than welcome to do a high-level technical review. I only did the proofreading part. You can certainly fix the typos and grammar that I listed above, if you so wish. I'm still in the middle of the GRUB bootloader stuff, so I'm trying to get through that (in the free time I have available).
Metadata Update from @alanbowman: - Issue assigned to alanbowman (was: pboy)
OK. I've assigned this to myself and I'll work on it this week. I'll take your recommendations above and use those to make updates, along with anything else I find.
@darknao , @pboy , @anthonymcglone - after reviewing this doc, this is very much not a Quick Doc. This is a fairly detailed technical overview on installing software from source.
Is there any objection to me cutting this down into an actual "How To and FAQ style documentation" sized topic?
The person who would understand all the technical details would never need this doc, and the person who needs this doc doesn't care about all the technical details. They just want to know what steps to take to install from source.
I agree, the article is a bit too long for QuickDocs How-To. It should concentrate on "How install software from source on Fedora", not in general.
At the same time, we should be careful not to cannibalize (too much) the work of Ramin Degham, which I just took over after 2 years of doing nothing.
But it may be that the two considerations are somewhat contradictory.
Another idea, we could take it as an tutorial. A tutorial may be longer than a how-to, and QuickDocs is considered to provide both types. Nevertheless, even a tutorial should concentrate on the on Fedora bit.
Question: Does Antora support Multipart Articles? Then we could split the text i 1. step-by-step how-to, 2. FAQ, 3. background knowledge/concepts.
Metadata Update from @pboy: - Issue priority set to: next meeting
Antora has a nav class = "pagination" with span class = "next" and span class = "previous". You can see this at the bottom of most pages in the Antora docs. Just picking one at random: https://docs.antora.org/antora/latest/content-source-repositories/ - scroll to the bottom to see the links.
nav class = "pagination"
span class = "next"
span class = "previous"
I haven't looked at this in detail, but the functionality is there.
Edit: this is also mentioned here - https://docs.fedoraproject.org/en-US/fedora-docs/contributing-docs/asciidoc-markup/#_pagination
I've pushed my changes for a pull request. I streamlined the content and made it more of a "how to" and less of a "how it works."
The existing content was too long and too detailed to really reuse. It would be better as a blog post or something similar.
Metadata Update from @alanbowman: - Assignee reset
Duplicated in #553
Metadata Update from @hankuoffroad: - Issue close_status updated to: duplicate - Issue status updated to: Closed (was: Open)
Log in to comment on this ticket.