iLiad Browse the Iliad sources online...

[hansel]

Hi All,

http://iliad.hpelbers.org/

I've generated html files from the sources recently released by Irex. They have syntax highlighting and some neat cross references. I'll refine (and document ) things later when I have some spare time, but it's a start...

If you prefer to browse things off-line (or would like to add this stuff to openiliad.com) you can fetch this: irexdox.tgz (huge file, 40MB!!!)

Happy hacking!

Edit (2008/11/02): I've just uploaded a much improved version: just select the item you want to explore and click on the 'files' or 'classes' tab. I'll create a proper home page later...

Edit (2008/11/06): Added newly released sources (erbusy, pagebar, powerMgr, scribble, settings), better indexing of static functions.

Edit (2008/11/10): Added new packages (pcshareMgr and connectionMgr), solved some defect links, added nice click-able call graphs

[ericshliao]

Great!!!
I've been struggled reading iRex's source code.

[Antartica]

Originally Posted by hansel

I've generated html files from the sources recently released by Irex.

Very nice.

Mmmm... Hansel, would you mind to add a link to this in OpenIliad's wiki page for developers if there are no bandwidth concerns?

The page I'm referring to is:

https://wiki.mobileread.com/wiki/OpenIliad_Developer

Thanks

[hansel]

Originally Posted by Antartica

Hansel, would you mind to add a link to this in OpenIliad's wiki page for developers if there are no bandwidth concerns?

The page I'm referring to is:

https://wiki.mobileread.com/wiki/OpenIliad_Developer

Thanks

I've added a link inhttps://wiki.mobileread.com/wiki/IRex_Developed_Software, they say I have unlimited bandwidth...

[hansel]

Originally Posted by hansel

I'll refine (and document ) things later when I have some spare time, but it's a start...

I've just uploaded a much improved version:

• one document tree per program / library
• (almost) everything cross-linked
• type definitions are now 'documented'

Have a look, it's a great way to discover new things! http://iliad.hpelbers.org/
Just select the item you want to explore and click on the 'files' or 'classes' tab. I'll create a proper home page later...

Have fun...

PS: Irex: thanks for releasing these sources, and for putting comments in them...

[Antartica]

Originally Posted by hansel

I've just uploaded a much improved version:

Wow! Thanks a lot Hansel. This will ease the studying of the sources .

Is there a way to add comments to that data?

I mean; right now I'm studying the einkfb part (well, when I have some time, which is not so often). I've started a wiki page for that (https://wiki.mobileread.com/wiki/ILiad_protocol:_einkfb) , but there are things that I would like to put in the source files, such as equivalent names ("struct transfer_buffer" of contentlister is named DrvPointsBuf or PointsBuf in liberscribble, for example).

[hansel]

Originally Posted by Antartica

Is there a way to add comments to that data?

Doxygen (the tool I use, see http://www.stack.nl/~dimitri/doxygen/starting.html) has a syntax to add documentation in the source code. Irex did a good start! The comments you add get automagically in the online docs...
An idea i'm pondering is this:

• Let's put the Irex sources in svn (or cvs)
• Allow developers to edit (add comments) them
• Generate new online docs once in a while

Of course we must only add comments... The resulting binaries must stay 100% identical.

What do you think? I'm willing to set this up, and I can host it. Hosting it on openilaid.com might even be a better alternative?

Side note: I think it would be a good idea to hav a dedicated wiki for the Iliad (to avoid name clashing with other devices or projects)
Adam B: can openiliad host svn and or a wiki?

[jharker]

We're actually in the process of putting up the iRex sources in the iLiad OS project at the MobileRead Dev Hub. They'll be hosted in svn, and we already have some tickets and rough planning in Trac. Hopefully I'll get the sources up in the next day or two, enough at least for a first version. I've been kind of putting it off until iRex posts the rest of the source code.

Please, please, feel free to put up tickets, make wiki pages, and generally contribute to the project!

Edit: Okay, the iLiad OS svn server now contains the iRex source code. However, for browsing I would still recommend hansel's site, since the svn source browser is pretty simplistic.

You can download the complete community-maintained iLiad source code from the iLiad OS svn server using this command:

svn co https://dev.mobileread.com/svn/iliados/trunk

I have also put some of the iRex-supplied source for upstream packages (busybox, X11, etc.) in the upstream folder. I'll be putting the rest up in a day or two after a few issues are hammered out.

[hansel]

Originally Posted by jharker

Edit: Okay, the iLiad OS svn server now contains the iRex source code. However...

Hi jharker,

Any ideas yet about how to maintain this code?

• Can it be edited to add documentation as Antarctica suggested? Or is is intended to be developed further?
• Will there be several parallel development branches?
• What will be *THE* official version?
• If we start documenting the existing code, how will this propagate?

Maybe we can document the original sources, and distribute new versions as patches to the official version?

I'll try to document my recipe for generating the browsable sources soon. In the mean time feel free to grab the tgz file and add the content to iliados if you like. I agree that the challenge is "to prevent splintering of the code base", while allowing fast community development...

happy coding!

[jharker]

Hey, hansel,

The goal for the iLiad OS project is to have a complete Linux distribution that is specific to the iLiad. Probably at first it will be distributed as individual upgrades for a few programs, then later as a single filesystem suitable for flashing to the iLiad. In the long run our goal is to introduce changes that will allow you to download new upgrades easily from community iDS servers by pushing the Connect button, just as you used to get upgrades from iRex.

We will release new versions following the convention and sequence of the iRex releases. So the first "official" community release will be 2.13, followed by 2.14, etc. (If iRex continues to release new versions then we may change our convention to avoid confusion, but my impression is that iRex is winding down development except for possibly bug fixes and a few minor features.) My ideal is to avoid having parallel development branches, unless for some reason it is strictly necessary. The iLiad OS project will be focused on achieving community-designed goals for UI, features, etc.

So iLiad OS will effectively become the new "official" version.

The "official" source code will be stored in the iLiad OS svn server, freely available for anyone to check out and edit. As community members create patches that implement new features, they will be submitted to the administrators (currently myself and Adam B.), who will proof them, test them, and then merge them into svn. This is how ongoing development efforts will be handled.

I don't really know exactly how source code documentation works. But assuming it takes the form of either a) comments within the source files, or b) additional files that are distributed with the source, then it seems like you could follow the standard process as for any other patch:

1. Check out the latest trunk source from svn.
2. Make your changes (i.e. add comments & documentation).
3. Submit patches containing the changes to an admin, who will merge them back into svn.

Documentation and development efforts are two sides of the same coin. They can and should happen at the same time.

Does that make sense? I'm fairly new to project administration, so advice and suggestions are happily welcomed!

[hansel]

Originally Posted by jharker

Does that make sense? I'm fairly new to project administration, so advice and suggestions are happily welcomed!

I develop software for 20 years now... Maintaining a (fairly) large set of interdependant software components is a *very* complex matter if these parts have different branches (say you want to use a new contentLister that uses a modified liberpc in combination with an older displayMgr...) As the number of components and versions increases, it quickly becomes a nightmare... These poblems can be managed by packemanager (like rpm, apt, pkg...), but packaging and releasing is not a trivial task!

Personally, I will probably never reflash my Iliad with an community developped OS (how to get back if it does'nt work?). I'll probably only install some improved progams (that stay compatible wite the rest of the system) or new ones.

Whatever one does, I believe that the following things are usefull for everybody (and an easy first step):

• add documentation to the (original sources)
• automatically generate docs from whatever set of sources

[hansel]

Originally Posted by jharker

I don't really know exactly how source code documentation works. But assuming it takes the form of either a) comments within the source files, or b) additional files...

Indeed. It's adding comments in the code with some special conventions...

[hansel]

Doxygen is a *COOL* tool. Together with dot (graphviz), can generate neat diagrams!
Attached is a caller graph for contenLister's, main() function. I'll add this feature to the on-line sources soon...

May the force be with you!

[hansel]

Added newly released sources (erbusy, pagebar, powerMgr, scribble, settings), better indexing of static functions.

http://iliad.hpelbers.org/

[Antartica]

Originally Posted by hansel

http://iliad.hpelbers.org/irexdox/deps.png

Very nice! . Thanks for your effort :-b.