Is there a single & complete (manual) book describing Haiku development from A to Z?
I’m making this question,because i got very tired & bored to surf all around Haiku’s website to find all docs that i need in one place.
Thanks.
1 Like
Hello. Short answer: No. But maybe the more close to a manual are the DarkWyrm tutorials:
3 Likes
I have looked at this material and I must admit that it is very poor for anyone who has started to study Haiku from scratch. Therefore, I hope that in the not too distant future, funds will be made available to write complete books on the subject.
Thank you.
What is it that you think is “poor” about it? Maybe you could tell us what kind of information you are looking for. Development of the OS itself? This is indeed not covered in these books, as they are aimed at beginners. Application development? There is quite a bit of it in there. There’s also an old O’Reilly book about application development for BeOS, most of which still applies to Haiku. It’s availabe for free nowadays, I think the link is on the Haiku website under the development section somewhere.
1 Like
I am looking for a single & complete book that fully describes the entire operating system, including its development.
perhaps you should check these resources:
- Haiku user guide Haiku User Guide - Contents
- Be Book The Be Book
- Haiku book The Haiku Book: Welcome to the Haiku Book
- Haiku internals site Welcome to Haiku internals’s documentation! — Haiku internals documentation
And that’s without mentioning the several pages of contents in blogs, mailing lists and forum topics about Haiku development
5 Likes
Yes,in fact this is a very big issue for me,this kind of fragmentation over all places is not very practical for me.
However thanks you anyway.
3 Likes
There are multiple documents targetting different audiences.
The user guide is, of course, for users. But it is still a good idea to read it to know how the system is used, and so that the new developments can fit into it.
The Be Book and Haiku book cover the same things, they are currently separated due to licensing issues on the Be Book (we are allowed to redistribute it, but not to change or update it). As a result, the Haiku Book is handled somewhat as an “extension” of the Be Book and you have to use the two of them. They are both meant for people writing applications or drivers, but that is also things we do in developing Haiku itself.
There are two “appendixes” to this: the Haiku Interface Guidelines and the Icon Guidelines. They are currently handled as separate documents, but I guess we will eventually merge them into the Haiku Book.
Finally, the “Haiku internals” one is for people working on the OS. It is meant to describe the team organization, workflow, as well as various things that are relevant only for people contributing directly to the operating system. It will not repeat what is already in the other documents, but it could reference them. It is a work I have started relatively recently and it is very incomplete for now. It’s a lot of work to add all the missing chapters, migrate and update existing info from old articles and blogposts on the website, etc.
12 Likes
I think that’s a bit harsh. FWIW, I believe most of the devs and this community at large don’t take offense by people expecting something without contributing themselves. Often, as newbies, they realistically can’t. Also, I think many experience Haiku’s rather polished (IMO) feel and expect a larger dev/community than we really are.
We do it all for ourselves and each other. If more people join, that’s great, but it’s not why we do it.
It’s when people get belligerent and ‘demand’ things, or tell us what and how to do it without having any stake in it, that it gets annoying and we get protective of our community.
[I wish you strength and good fortune, dbs, for your current RL struggles!]
5 Likes
@Tarasenko I believe that this is a great opportunity for someone like you to start working on such a book, since it sounds like you have the vision of what should be delivered. You could document the development process as you discover it and pitch it at the right level for your audience.
2 Likes
Is that all we have to reply, “just do it yourself”?
The problem is not really the vision. We already know what should be in the book and it is painfully annoying to not have it. A massive amount of time is wasted by people trying to join the development team and struggling to find the info they need, as the only way to do it is… to ask the people who know, over lengthy email threads and IRC chats.
We really should do better in that area, and we’re not going to do that by asking newcomers to write the docs themselves. Otherwise, we are going to remain a small team, with people outside it who will continue to say “I would contribute if only I could understand how any of this works”. This applies to all things: the coding guidelines, how to submit a patch, how and when someone can get commit access to the repository, how is a driver written and what components are involved, etc. Some of these things are factual and technical and can simply be documented, but others need to be debated because they are not written anywhere and each of us possibly has a different idea about them. And we can’t expect someone outside the team to be able to achieve that. How do I know? Because the last attempt ended in disaster. See this pull request that has been open for 2 years: Organized Haiku Guides by n0toose · Pull Request #506 · haiku/website · GitHub the person who did this is now involved in Serenity OS instead, because the community there was far more welcoming.
And indeed this thread, with one person replying with insults and another with “just do it yourself” certainly does not help with improving on this.
9 Likes
Yes, unfortunately you hear the “do it yourself” too often.
Even as part of the Google summer of code, writing documentation is not necessarily the right thing to do, since people who have a lot of time to explain something are also needed for support (to get straight to the point 
).
The problem is that the developers have to deal with programming, problem-solving and, due to pressure from the community, have to keep working on new betas .
Not every programmer can write instructions, that’s the way it is. There are people who find it easy and others who have difficulties with it. I could, but I don’t have the necessary knowledge about programming because I think there is a lack of documentation for programmers in particular.
There are instructions for the system in parts (Haiku Guides, BeSly knowledge base …). It is therefore difficult to find someone who, firstly, has the necessary experience with programming haiku and, secondly, likes to write. I think that’s the real problem.
1 Like
No it wasnt “just do it yourself”. It was: If you have the itch, scratch it. It was a gently delivered suggestion of the idea to help and contribute.
In fact, I’d say it was much softer than “patches welcome”, something I can quote from you 16 times, according to forum search results.
Writing a book will take a full time developer away from developing. And I see someone asking that “funds will be made available”, when there are barely funds to cover the one paid developer already working for the project. When, in fact, it looks as though the funds to pay that developer could run out if donations dont increase. And somebody who asks this question cannot be aware of the current lack of resources in the project and the fact that they might be able to help.
If you think that some developer resources are better spent on writing documentation, and that it cant be done by a newcomer, then I am inclined to agree with you, because I dont have the relevant experience to make that judgement. But I don’t understand the need to misquote and lambast me for suggesting that someone might help themselves and others by contributing.
2 Likes
I don’t. What should be in it that isn’t already documented somewhere else? I don’t mean to be ironic, I’m asking seriously.
2 Likes
And can it be serious, that if ALL infos about Haiku were available but neatly divided into categories, that the OP would still complain about it not being a single book? I mean there are many different categories like Haiku history, architecture, driver dev, app dev, various APIs.
Starting with simple things:
- The source repository directory layout
- The main jam targets used in Haiku
- The buildtools repository, what’s in it, why it exists
- How to navigate the bugtracker and find things to work on (the current instruction is “look at this list of 5000 issues and find something interesting”)
- The governance of the project, how do people get commit access, how there are no “maintainers” for specific parts of the code and everyone is expected to know everything, how that can’t possibly be the case so there are, in fact, default owners for each compoment in Trac that provide a good idea of who is responsible for each component. How we communicate, which channels we use, why we have chosen them (free software tools, and asynchronous modes of communication), what their limitations are, what we are doing about it (such as using the forum more and the mailing lists less)
- An up to date documentation on how to write and run unit tests (the current doc is 3 different blog posts, one of which still references CVS as the place the Haiku source are stored)
- Tips for efficient testing and debugging: how to use network boot to quickly iterate on testing a driver, how to make best use of qemu, how to test changes to an application or library from inside Haiku without rebooting and recompiling a full filesystem image
More “in-depth” stuff:
- Documentation for the internals of each “kit” and “server”, for example, how the net_server loads network drivers, how it assign network protocol to each network interface
- A complete and up to date guide to the driver architecture, how busses and bus_managers work, etc
- Complete and up-to-date documentation on the graphics stack, including the remote_app_server with both the html5 and native backends, and the test_app_server
- Proper documentation for the file cache and block cache and the vfs, and what services are provided by each of these, and how they connect to filesystem drivers,
- The policies for ABI stability for releases and beta versions, and the various things we have set up to avoid breaking applications all the time: libshared, symbol visibility, “fragile base class” padding
- Documentation on porting Haiku to a new architecture, where to start, how to use bootstrap builds and how to avoid using them since they don’t actually work, tips for debugging the early boot process on both real hardware and virtual machines.
I think that would be a good start? Anything missing?
10 Likes
I used to say this, but someone complained about it a few years ago and they are correct. So I use it more carefully now, either when answering someone who is already a member of the Haiku community, or when someone act like they know everything or say something along the lines of “this should not be very hard to do”.
Here, the request seems perfectly reasonable to me. Our documentation deserves to be better.
Your reply on its own I think would be fine, but it arrived unfortunately after a less politely worded message, and as a result, ended up adding to it and creating something that probably makes newcomer feel rather unwlecome. This is probably unintentional from you, but it is how I perceived it.
And I guess I’m a bit tired and should spend some time away from computers this week-end and come back in a more calm state. Sorry about that.
3 Likes
Well, I’m sorry to have given that impression, then. I will stay away from suggestions like this in future, so I learned something too.
1 Like
Yes,500 euros in 2022.
4 Likes