RFC: modify buildsystem docs in README.md #825
Conversation
|
Improved docs are always welcome. Before putting much work into this, we should discuss on #765 as it will change many of the existing folders. |
I'm already finished. I'd prefer to have this merged fairly soon, as anyone how like to use our buildsystem now, would need to invest much debugging effort into it, until he gets to know, where to configure anything. |
|
Besides that, regarding our current development velocity, I don't think we will have a decision on #765 within the next 1.5 Years. |
README.md
Outdated
| * a tutorial ([en](https://wiki.freifunk.net/Berlin:Firmware:En:Howto) / [de](https://wiki.freifunk.net/Berlin:Firmware:Howto)) on router configuration | ||
| More user relevant information on the firmware are on the wiki page at: | ||
| https://wiki.freifunk.net/Berlin:Firmware. There you can also find the | ||
| * [ReleaseNotes](https://wiki.freifunk.net/Berlin:Firmware/v1.0.2) and |
There was a problem hiding this comment.
Hedy-1.0.6 is out and should be referenced here. But this can be a separate commit.
There was a problem hiding this comment.
Is it possible to use a variable which accesses the latest tagged release version. (for the separate commit which will someday materialize)
There was a problem hiding this comment.
As the Readme belongs to the Codebase of a release, releasing something with an old or template value here, will end in having this template in the released Readme. Updating it after releasing creates a new version of the file (commit) which should cause to release again. So the never ending loop has started ...
In long-term I suggest to get rid of the release-history in the Readme of the firmware-buildsystem, like I did here: https://github.com/freifunk-berlin/firmware/tree/745bda009b313cf3ce4eaacd82e232a4644f8a03
There was a problem hiding this comment.
As the page for v1.0.6 does not exist, I linked the page for v1.0.3
README.md
Outdated
|
|
||
| patches/ - Patches against the OpenWRT directory | ||
| packagelists/ - Package Lists | ||
| profiles/ - List of router profiles for each architecture - names come |
There was a problem hiding this comment.
probably use "target architecture" to keep the common target term
README.md
Outdated
| patches/ - Patches against the OpenWRT directory | ||
| packagelists/ - Package Lists | ||
| profiles/ - List of router profiles for each architecture - names come | ||
| from the Imagebuilder |
There was a problem hiding this comment.
is it worth to mention "make info" here?
| The default target is `ar71xx-generic`. For a complete list of supported targets | ||
| look at `configs/` for the target-specific configs. Each of these targets need a | ||
| matching file in `profiles/` with the profiles (boards) that should be build | ||
| with the imagebuilder. |
There was a problem hiding this comment.
"should be build by the imagebuilder"?
There was a problem hiding this comment.
"should be built by" would be the queen's english.
| should work at least in theory. Wifi should be ath9k / ath10k. mt76 also appears | ||
| to work. | ||
|
|
||
| You can use the Imagebuilder to get a list of all supported models for a |
There was a problem hiding this comment.
Probably the better place, than the mentioned above, to reference "make info" if we want to reference it at all.
README.md
Outdated
| [http://buildbot.berlin.freifunk.net/buildbot/unstable/](http://buildbot.berlin.freifunk.net/buildbot/unstable/) | ||
| Note that in the directory there is no reference to the branch name; unstable builds can be identified by build number only. | ||
| Note that in the directory there is no reference to the branch name; unstable | ||
| builds can be identified by their build number only. |
There was a problem hiding this comment.
Are you willing to referernce the VERSION.txt file here
…m. Wrap lines to meet needs of 80-char-terminal.
| * a tutorial ([en](https://wiki.freifunk.net/Berlin:Firmware:En:Howto) / [de](https://wiki.freifunk.net/Berlin:Firmware:Howto)) on router configuration | ||
| More user relevant information about the firmware are on the wiki page at: https://wiki.freifunk.net/Berlin:Firmware. | ||
| There you can also find the | ||
| * [ReleaseNotes](https://wiki.freifunk.net/Berlin:Firmware/v1.0.3) |
There was a problem hiding this comment.
To reflect the current state: It feels to me, that we should not reference the wiki here, as nobody takes care of updating the pages. It seems best to reference the Github-release pages (https://github.com/freifunk-berlin/firmware/releases) here, which link to the correct ReleaseNotes of the corresponding release.
|
|
||
| The idea is to download OpenWrt via git, patch it with all patches in the | ||
| `patches/` folder and configure it according to the configuration snippets in | ||
| `configs`. Then use the OpenWrt buildsystem to build all packages and the |
There was a problem hiding this comment.
should be configs/ , as it's a folder
| `patches/` folder and configure it according to the configuration snippets in | ||
| `configs`. Then use the OpenWrt buildsystem to build all packages and the | ||
| Imagebuilder and use the latter to assemble the final image with lists of | ||
| packages in packages for the router. |
There was a problem hiding this comment.
"with lists of packages in packaglists/ for the router.
| `configs`. Then use the OpenWrt buildsystem to build all packages and the | ||
| Imagebuilder and use the latter to assemble the final image with lists of | ||
| packages in packages for the router. | ||
| All additional packages can be found at http://github.com/freifunk-berlin/packages_berlin. |
There was a problem hiding this comment.
should we mention "gluon-packages" and "freifunk-potsdam-packages" also. (not shure if ffp-packages made it up to this repo already)
| ``` | ||
| :: Settings | ||
|
|
||
| config.mk - OpenWrt git repository, revision, select what package lists to build |
There was a problem hiding this comment.
"OpenWrt git repository, revision" is controlled by modules-file
| :: Settings | ||
|
|
||
| config.mk - OpenWrt git repository, revision, select what package lists to build | ||
| feeds.conf - OpenWrt feeds.conf that is used for the package feeds during build |
There was a problem hiding this comment.
"feeds.conf" is converted to modules
| config.mk - OpenWrt git repository, revision, select what package lists to build | ||
| feeds.conf - OpenWrt feeds.conf that is used for the package feeds during build | ||
|
|
||
| configs/ - further configurations |
There was a problem hiding this comment.
"further configurations" replace by "snippets of the OpenWrt config-options (compare to call "make menuconfig" in openwrt/)" or something alike
| some boards to initially install OpenWrt. | ||
| As you notice there are several different image variants ("manual", "notunnel", | ||
| etc.). | ||
| + These different *packages lists* are defined in `packages/`. See the |
There was a problem hiding this comment.
packages/ --> packagelists/
There was a problem hiding this comment.
You talk here on the "firmware" folder, right? Then this packages folder is just the storage-repo of all packages available.These packages will be included according to the flavors in packagelists/ to the image or used as source then running opkg install on the router.
| All branches with names not fitting the "X.Y.Z" pattern are built and put into | ||
| the "unstable" directory: [http://buildbot.berlin.freifunk.net/buildbot/unstable/](http://buildbot.berlin.freifunk.net/buildbot/unstable/) | ||
| Note that in the directory there is no reference to the branch name; unstable | ||
| builds can be identified by build number only. |
There was a problem hiding this comment.
referencing the VERSION.txt file? As this is the best place to look up on which branch and revision a build is based on.
| the codename in the README and config files (./configs/*) | ||
| For a new release, create a new branch. The branch name must be a semantic | ||
| version number. Make sure you change the semantic version number and, for major | ||
| releases, the codename in the README and config files (`./configs/`) |
There was a problem hiding this comment.
(./configs/) --> in all other places we did not prefix the path by "./"
|
@SvenRoederer There were 37 (±2) requests for changes in total. Please feel free to include them into the README-File. It might be faster to do it by yourself, then writing me, what I should change. I will no longer invest effort into this. You seem to be the only one, who knows how this buildsystem works. Sadly, the documentation will still document a different state than the current one. |
That's the downside of having the PR source from your private Repo-fork ... Only you have permission to commit to it. My impression was, that the most of the open changes were were most "consistency of terms" and generic comments.
I got used to it and found some smart ideas inside. Sadly I seems to be the only one still working on it, as the "old" developers (@sarumpaet @booo @andrenarchy @lynxis ) seem to have retired.
Indeed your updated documentation somehow based on the outdated system before switching to "modules"-file. But thanks for your work so far. I'll reopen, in case someone else likes to continue here. |
This is meant to be an first improvement for the issues in documentation addressed in #824. This commit mainly takes some of documentation of weimarnetz and adds that to our README.md