Suggestions: should we have wiki for SheepShaver internals?

About SheepShaver, a PPC Mac emulator for Windows, MacOS X, and Linux that can run System 7.5.3 to MacOS 9.0.4.

Moderators: Cat_7, Ronald P. Regensburg, ClockWise

Post Reply
User avatar
rickyzhang
Apple Corer
Posts: 205
Joined: Mon Sep 15, 2014 7:59 pm

Suggestions: should we have wiki for SheepShaver internals?

Post by rickyzhang »

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/ma ... /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.
There is an App for that!
https://github.com/rickyzhang82
kataetheweirdo
Master Emulator
Posts: 312
Joined: Sun Feb 01, 2009 4:55 pm

Re: Suggestions: should we have wiki for SheepShaver interna

Post by kataetheweirdo »

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.
User avatar
rickyzhang
Apple Corer
Posts: 205
Joined: Mon Sep 15, 2014 7:59 pm

Re: Suggestions: should we have wiki for SheepShaver interna

Post by rickyzhang »

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.
There is an App for that!
https://github.com/rickyzhang82
User avatar
Cat_7
Expert User
Posts: 6121
Joined: Fri Feb 13, 2004 8:59 am
Location: Sittard, The Netherlands

Re: Suggestions: should we have wiki for SheepShaver interna

Post by Cat_7 »

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?

Best,
Cat_7
User avatar
rickyzhang
Apple Corer
Posts: 205
Joined: Mon Sep 15, 2014 7:59 pm

Re: Suggestions: should we have wiki for SheepShaver interna

Post by rickyzhang »

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/viewto ... =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

----------update

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
There is an App for that!
https://github.com/rickyzhang82
User avatar
rickyzhang
Apple Corer
Posts: 205
Joined: Mon Sep 15, 2014 7:59 pm

Re: Suggestions: should we have wiki for SheepShaver interna

Post by rickyzhang »

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:

https://github.com/cebix/macemu/wiki/Developer-Guide
There is an App for that!
https://github.com/rickyzhang82
User avatar
adespoton
Forum All-Star
Posts: 4208
Joined: Fri Nov 27, 2009 5:11 am
Location: Emaculation.com
Contact:

Re: Suggestions: should we have wiki for SheepShaver interna

Post by adespoton »

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.
Post Reply