Oolite Bulletins

For information and discussion about Oolite.
https://bb.oolite.space/

Developer Documentation

https://bb.oolite.space/viewtopic.php?t=21461

Page 1 of 1

Developer Documentation

Posted: Thu Oct 19, 2023 7:03 am
by hiran
We now have a new site https://ooliteproject.github.io/oolite/

It contains developer documentation. So far this is the Doxygen generated stuff, but we can extend it to hold more than that if we want to. As this documentation can easily be updated with the code I do not believe this would replace the wiki. Instead it can complement what we have and is auto-generated with each code change so it should always be up to date.

Re: Developer Documentation

Posted: Thu Oct 19, 2023 7:22 am
by another_commander
Regarding entry points: The one in the Cocoa folder is for the Mac build and the one in the SDL folder is for the Windows and Linux ones. Right now there seems to be a mistake in the links in the generated documentation and they both point to the Cocoa main.m.

Re: Developer Documentation

Posted: Thu Oct 19, 2023 11:14 am
by hiran
Thank you for the hint. While I revisited that code anyway, I tried to understand bits and place that into into a Doxygen style comment.
But now look what happened: The two entry points are not equivalent.

Should this be the answer to the question raised here?
https://bb.oolite.space/viewtopic.php?p=290063#p290063

Re: Developer Documentation

Posted: Thu Oct 19, 2023 2:59 pm
by another_commander
I would be genuinely surprised if that was the answer to the question you linked to.

Re: Developer Documentation

Posted: Thu Oct 19, 2023 3:21 pm
by hiran
another_commander wrote: ↑Thu Oct 19, 2023 2:59 pm
I would be genuinely surprised if that was the answer to the question you linked to.
I am surprised, too. But I cannot find a better explanation. :roll:

So far it looks to me like the linux/windows version processes one command line parameter, whereas the Mac version processes none.
Where else could command line evaluation happen?

Re: Developer Documentation

Posted: Thu Oct 19, 2023 4:49 pm
by another_commander
hiran wrote: ↑Thu Oct 19, 2023 3:21 pm
So far it looks to me like the linux/windows version processes one command line parameter, whereas the Mac version processes none.
That is correct. -load is available only for the GNUstep builds.

Re: Developer Documentation

Posted: Thu Oct 19, 2023 6:05 pm
by hiran
another_commander wrote: ↑Thu Oct 19, 2023 4:49 pm
hiran wrote: ↑Thu Oct 19, 2023 3:21 pm
So far it looks to me like the linux/windows version processes one command line parameter, whereas the Mac version processes none.
That is correct. -load is available only for the GNUstep builds.
The even more puzzling part is: what happened to all the other command line options?
https://wiki.alioth.net/index.php/Hidde ... parameters
I cannot believe they were documented but did not exist.
I also cannot believe they were lost through code changes and noone noticed.

Re: Developer Documentation

Posted: Thu Oct 19, 2023 7:19 pm
by hiran
hiran wrote: ↑Thu Oct 19, 2023 6:05 pm
The even more puzzling part is: what happened to all the other command line options?
https://wiki.alioth.net/index.php/Hidde ... parameters
I cannot believe they were documented but did not exist.
I also cannot believe they were lost through code changes and noone noticed.
Ok, I found some suspicious locations. In some of them additional command line options are detected.

Code: Select all

$ grep -rHn NSProcessInfo *
src/Core/OXPVerifier/OOOXPVerifier.m:84:	arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOOpenALController.m:54:		arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOOpenGLExtensionManager.m:549:	NSArray 		*arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOLogHeader.m:156:		NSString *systemString = [NSString stringWithFormat:@OS_TYPE_STRING " %@", [[NSProcessInfo processInfo] operatingSystemVersionString]];
src/Core/OOLogHeader.m:188:		NSString *systemString = [NSString stringWithFormat:@OS_TYPE_STRING " %@", [[NSProcessInfo processInfo] operatingSystemVersionString]];
src/Core/Universe.m:10937:	arguments = [[NSProcessInfo processInfo] arguments];
src/Core/Entities/PlayerEntity.m:10001:		NSArray* arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOCPUInfo.m:85:	sNumberOfCPUs = [[NSProcessInfo processInfo] processorCount];
src/SDL/MyOpenGLView.m:178:	arguments = [[NSProcessInfo processInfo] arguments];
src/SDL/MyOpenGLView.m:2727:	NSArray* cmdline_arguments = [[NSProcessInfo processInfo] arguments];
$
That code is tricky! I would not even know where/how to document such distributed functionality.

Re: Developer Documentation

Posted: Sun Oct 22, 2023 10:50 am
by hiran
hiran wrote: ↑Thu Oct 19, 2023 7:19 pm
hiran wrote: ↑Thu Oct 19, 2023 6:05 pm
The even more puzzling part is: what happened to all the other command line options?
https://wiki.alioth.net/index.php/Hidde ... parameters
I cannot believe they were documented but did not exist.
I also cannot believe they were lost through code changes and noone noticed.
Ok, I found some suspicious locations. In some of them additional command line options are detected.

Code: Select all

$ grep -rHn NSProcessInfo *
src/Core/OXPVerifier/OOOXPVerifier.m:84:	arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOOpenALController.m:54:		arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOOpenGLExtensionManager.m:549:	NSArray 		*arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOLogHeader.m:156:		NSString *systemString = [NSString stringWithFormat:@OS_TYPE_STRING " %@", [[NSProcessInfo processInfo] operatingSystemVersionString]];
src/Core/OOLogHeader.m:188:		NSString *systemString = [NSString stringWithFormat:@OS_TYPE_STRING " %@", [[NSProcessInfo processInfo] operatingSystemVersionString]];
src/Core/Universe.m:10937:	arguments = [[NSProcessInfo processInfo] arguments];
src/Core/Entities/PlayerEntity.m:10001:		NSArray* arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOCPUInfo.m:85:	sNumberOfCPUs = [[NSProcessInfo processInfo] processorCount];
src/SDL/MyOpenGLView.m:178:	arguments = [[NSProcessInfo processInfo] arguments];
src/SDL/MyOpenGLView.m:2727:	NSArray* cmdline_arguments = [[NSProcessInfo processInfo] arguments];
$
That code is tricky! I would not even know where/how to document such distributed functionality.
I did not like the fact that command line argument processing is distributed over so many classes/methods. Yet what can I do?
Then I found that Doxygen allows grouping some items into a special page, and that's what I did.

I defined a group 'cli' here:
- https://github.com/OoliteProject/oolite ... ro.dox#L65

Then I added relevant code pieces here:
- https://github.com/OoliteProject/oolite ... fier.m#L73
- https://github.com/OoliteProject/oolite ... ller.m#L46
- https://github.com/OoliteProject/oolite ... ger.m#L541
- https://github.com/OoliteProject/oolite ... e.m#L10928
- https://github.com/OoliteProject/oolite ... ty.m#L9943
- https://github.com/OoliteProject/oolite ... main.m#L53
- https://github.com/OoliteProject/oolite ... iew.m#L153
- https://github.com/OoliteProject/oolite ... main.m#L11

Doxygen's output for the group looks like this:
https://ooliteproject.github.io/oolite/group__cli.html

And I am surprised to see five group elements although I expected 8. Any idea what might prevent three of them from showing up?

Re: Developer Documentation

Posted: Mon Oct 23, 2023 6:17 am
by hiran
When further looking at a developer's needs, somehow I feel doxygen is just not sufficient. Future developers would also have to guess how to setup their environment and make compilation/debugging work. Likely the choice of tools and procedures varies throughout the operating systems.

I may be guessing wrongly, but on the Apple Mac this was likely all handled by XCode.
What is required on Linux? What is required on Ubuntu? How is the code being developed and tested today?

Let's share/document whatever we know so we can build and maybe improve on it.
All times are UTC
Page 1 of 1

Powered by phpBB® Forum Software © phpBB Limited