Suggestions: should we have wiki for SheepShaver internals?
Page 1 of 1

Author:  rickyzhang [ Fri Aug 11, 2017 3:16 am ]
Post subject:  Suggestions: should we have wiki for SheepShaver internals?

SheepShaver and BasiliskII don't have a good internals design documentation for developers perspective. I'd like to have a wiki page in this website (if possible) for developers all over the world, who want to write and share whatever they find when they read SheepShaver or BasiliskII code.

If we can have some documentation in the core part of emulation, it will be great for whoever want to maintain these two projects in the future.

Recently, I fixed sheep_net module in Linux and wrote a doc to explain how things work. https://github.com/cebix/macemu/tree/master/BasiliskII/src/Unix/Linux/NetDriver

I admit I'm not a technical writer. The doc is not great but is better than nothing.

Whenever tracing bugs, developers must read the F*** code and know a thing or two in that specific area at that time. Sending a doc to Github needs maintainers approval. It is a hassle. It would be great if we can do that in wiki format.

Author:  kataetheweirdo [ Fri Aug 11, 2017 9:40 am ]
Post subject:  Re: Suggestions: should we have wiki for SheepShaver interna

Oh, definitely. I started my own topic on this b/c Sheepshaver was so poorly documented. Unfortunately, it didn't gain any traction, namely because demand for updates on Sheepshaver is much higher than what any developer can deliver and there isn't much time anyone is dedicating themselves to examining Sheepshaver's code.

Technical documentation for both Sheepshaver and BII is pretty poor honestly. I do know that Gwenole migrated the 68k core from WinUAE over a decade ago, but in turn, the PPC plug-in for WinUAE was based on PearPC. There have also been loads of fixes for the 68k CPU core used in WinUAE since 2003/4, not the least of which being MMU support. This also affects Sheepshaver and its 68k emulation, as both emus share the same code for this.

Don't forget about this gem of a topic either. neozeed didn't go into great detail with how horribly 90's/00's the code is, complete with haphazard updating to C++0x.

Author:  rickyzhang [ Fri Aug 11, 2017 12:20 pm ]
Post subject:  Re: Suggestions: should we have wiki for SheepShaver interna

The last link explains the segfault in SheepShaver.

If this sites can't provide a wiki, can we find an alternative place to do it? Github/Wikipeida? But the difficult part is to let those interested in sharing their finding to come to this central location.

I always believe the force of community. Given 6 billions population, we must have someone feel so fed up and make a change.

Author:  Cat_7 [ Fri Aug 11, 2017 12:27 pm ]
Post subject:  Re: Suggestions: should we have wiki for SheepShaver interna

Several years ago I tried to start the same initiative. I created a page on our wiki and invited all then active developers to contribute their knowledge. As no-one was interested, nothing came of it ;-)

Do you think times have changed?


Author:  rickyzhang [ Fri Aug 11, 2017 1:42 pm ]
Post subject:  Re: Suggestions: should we have wiki for SheepShaver interna

Well. Developer hate writing documentation in general even they got paid to do so. Their argument is that source code is the best documentation you'd ever have.

I know that's BS as I were a statistician developer. The code is enigma behind the complicated math model. If we don't write any good doc to explain our ideas, our jobs are saved. There is a funny story about CITI bank. They fired all their Quants in financial crisis who works on their credit default swap and CDO in-house pricing. You know what nobody understand how their code works.

But I believe there are enthusiast who love to blog and share their ideas and finding. We only share pieces here and there. We are not asking for writing a book about this. Like the page from kataetheweirdo http://www.emaculation.com/forum/viewtopic.php?f=20&t=9099

If I can find this, that would save me and others a lot of time. I know the one who write their codes have gone. They won't maintain it or write anything. But I believe someone will.

The key is to:

1. Make it easy to access -- that implies searchable and developers who know a thing or two can notice it. May be add the link in macemu git repo.

2. Democratic writing process like wiki


In fact, macemu github allow you to write wikipage. It should be the better place to start. https://github.com/cebix/macemu/wiki/Developer-Guide

Author:  rickyzhang [ Sat Aug 12, 2017 9:55 am ]
Post subject:  Re: Suggestions: should we have wiki for SheepShaver interna

There is no place better than add wiki developer guide documentation in macemu github upstream. Last year, I use lxr to build BII source tree and try to read its emulation core. But this ends up nowhere. I hope writing something down can make me finish this long over due job.

Here is my initiative:


Author:  adespoton [ Tue Aug 15, 2017 5:51 pm ]
Post subject:  Re: Suggestions: should we have wiki for SheepShaver interna

I don't have much time, but I'd be happy to put in some time doing edits/reviews. Not only have I poked around inside SheepShaver and BII in the past, but in a past life I was a technical writer, so translating source code into user-readable documentation is near and dear to me :)

But I'm talking about 5-10 minutes available per month -- I'm already spread pretty thin. [edit] and I've been following your emails to BII-Devel; haven't had a chance to look at your github repo yet.

Page 1 of 1 All times are UTC
Powered by phpBB® Forum Software © phpBB Group