Hub Libraries

ID:138113
 
Mar 26 2001, 6:58 am (Edited on Mar 26 2001, 10:18 am)
I have probably not done a very good job presenting a description of how the new hub-distributed libraries are supposed to work.

First of all, you would almost never want to use the "Download URL" option. Instead, you want to upload a zip package to the hub and let Dream Seeker handle the installation. Here's why: a package distributed directly through the hub can be included as a dependency in another hub distribution.

For example, the maze demo that I posted contains a file called include.txt, which has a single entry: Dan.maze. When Dream Seeker installs Dan.MazeDemo, it automatically checks to see if the library Dan.maze is installed and installs it if necessary. That is better than including the library verbatim in every project that uses it, because if the library gets updated, you don't have to re-upload all of the other projects that make use of it. That's especially important if some of the projects that depend on the library were written by other people.

Another thing I may have failed to mention previously is that the installation location of all libraries is now determined by their path in the hub. The library Dantom.CGI goes in lib/Dantom/CGI and must therefore be included as include<Dantom/CGI> rather than the old method which was include<html/CGI.dm>.

This scheme prevents filename conflicts between different library writers. When you supply a zip package to the hub, Dream Seeker automatically installs it in the correct location, so that is another reason to use that method of distribution.

Finally, I did not intend for the "long description" to be a full description of the library interface. It should list the functionality so that someone who is looking for a library can tell if it has the desired features.

For describing the interface, there are a number of options. You could do it in readme.html (or readme.txt). The advantage of doing that is that when the library gets installed by Dream Seeker (even if it is just a dependency of another project), the user will be presented with the option of viewing the readme file. That would be an appropriate place to stick copyright and licensing information.

You could also include the documentation in a separate file and just link to it from the readme file. For example, a library with a big revision history could publish recent changes in the readme and the full docs in a separate file.

We will also soon be adding the ability to add on to the built-in compiler language reference so that your library's own procedures and objects can be found there along with the core DM definitions.

--Dan
Mar 26 2001, 6:15 pm
On 3/26/01 9:58 am Dan wrote:
I have probably not done a very good job presenting a description of how the new hub-distributed libraries are supposed to work.

And of course, since I'm the only other person who has posted there, we all know exactly whom this post is directed at. ;-)

First of all, you would almost never want to use the "Download URL" option. Instead, you want to upload a zip package to the hub and let Dream Seeker handle the installation. Here's why: a package distributed directly through the hub can be included as a dependency in another hub distribution.

For example, the maze demo that I posted contains a file called include.txt, which has a single entry: Dan.maze. When Dream Seeker installs Dan.MazeDemo, it automatically checks to see if the library Dan.maze is installed and installs it if necessary. That is better than including the library verbatim in every project that uses it, because if the library gets updated, you don't have to re-upload all of the other projects that make use of it. That's especially important if some of the projects that depend on the library were written by other people.

What's the tree structure of the zip package?

Another thing I may have failed to mention previously is that the installation location of all libraries is now determined by their path in the hub. The library Dantom.CGI goes in lib/Dantom/CGI and must therefore be included as include<Dantom/CGI> rather than the old method which was include<html/CGI.dm>.

This sounds like a better change, but it'll be very hard to get used to...

This scheme prevents filename conflicts between different library writers. When you supply a zip package to the hub, Dream Seeker automatically installs it in the correct location, so that is another reason to use that method of distribution.

Finally, I did not intend for the "long description" to be a full description of the library interface. It should list the functionality so that someone who is looking for a library can tell if it has the desired features.

Well, I kinda do both; mostly, I just took the description word for word from my library comment header, converted it to HTML, and used that.

For describing the interface, there are a number of options. You could do it in readme.html (or readme.txt). The advantage of doing that is that when the library gets installed by Dream Seeker (even if it is just a dependency of another project), the user will be presented with the option of viewing the readme file. That would be an appropriate place to stick copyright and licensing information.

So I would add readme.txt to the zip file, right? (An HTML, however snazzy, is a bit less desirable than the easy-to-read-and-format plain-text)

You could also include the documentation in a separate file and just link to it from the readme file. For example, a library with a big revision history could publish recent changes in the readme and the full docs in a separate file.

So you're saying something like... Spuzzum.copyright? Or are you talking about including another file in the package and then having a hyperlink in readme.html? Or even just hosting my copyright info on a separate web page (I have one that I need to start using)?


We will also soon be adding the ability to add on to the built-in compiler language reference so that your library's own procedures and objects can be found there along with the core DM definitions.

WHOA! Now that's good... very good. We'd make similar formatting too, I presume? Something like;

<center><font size=+2>s_missile() proc</font></center>

See also:
  • missile() proc
  • walk_line() proc

    Arguments:
  1. s_missile(icon,src,trg,lag=1,homing=0)
  2. s_missile(icon,icon_state,src,trg,lag=1,homing=0)
  3. s_missile(ref,src,trg,lag=1,homing=0)
  4. s_missile(/obj/fireball,src,trg,lag=1,homing=0)


Returns:
  • Procedure immediately returns but continues to process in the background.

    In the first format, create icon at src and move it on a straigh path towards trg, not taking obstacles into account, moving with lag delay between each successive step. If homing is specified, if the target moves the graphical missile will continue to follow the target. This effect is "graphical-only"; meaning that though it is possible to affect the graphical icon, it is designed with the intent that you would not do so (the other functions do that).

    In the second format, except for providing an icon state, it follows the same process as the first.

    In the third format, move ref to src loc and move it on a straight path towards trg, not taking obstacles into account... [and so on]


    Am I right?


    Anyway, I'll delete all of my former entries...
Mar 27 2001, 5:15 am
In response to Spuzzum

And of course, since I'm the only other person who has posted there, we all know exactly whom this post is directed at. ;-)

No. It was directed at one of the other Spuzzum clones, so don't take it personally!


What's the tree structure of the zip package?

In the hub creation wizard, if you select "Zip Package", it will give you an example. For libraries, it would typically be something like this:

MyLib/
   MyLib.dm
   readme.html   (optional readme file)
   include.txt   (optional list of dependencies)
   misc          (whatever other files you need)


It is best to name the hub entry the same as the zip directory, because DS always installs in a directory generated from the hub entry name (Dantom.CGI --> lib/dantom/cgi). If all the files in the zip are in a directory by the same name as the base installation directory, it puts them directly in there.

For example, the files in the CGI zip package are all inside of a directory called CGI, so they get installed to lib/dantom/cgi/CGI.dm etc. If it was zipped in a different directory (such as MyCGI), it would get installed as lib/dantom/cgi/MyCGI/CGI.dm.

Or you can just create a flat zip file with all the files in the top directory and that would work too. I don't like flat zip files, because if I accidentally unzip one without creating a sub-directory, it is annoying to have to remove all of the files that it extracted. But since this process is all handled automatically by DS, that is not a big concern.

In the end, all that matters is that the .dm file and the directory have the same name, because then you can include it by just including the directory. Of course, if you want to pack several libraries into one directory, that's ok too. The user would then include each .dm file separately, or you could provide a single .dm file (same name as the directory) that includes all of them.


So I would add readme.txt to the zip file, right?

Yes. That's all there is to it. Now that I think about it, there may be some problems with end-of-line conversion, but since I'm currently the only one using DS on a non-windows platform, that is not a big concern yet. I will make the zip extractor do the conversion in the future.

So you're saying something like... Spuzzum.copyright? Or are you talking about including another file in the package and then having a hyperlink in readme.html? Or even just hosting my copyright info on a separate web page (I have one that I need to start using)?

Any of the above!


WHOA! Now that's good... very good. We'd make similar formatting too, I presume?

Yes. The compiler expects a standard format to the html file. We'll publish that when we get this working. It would be nice to be able to create the reference entries in XML and then translate that into the final html doc, because the current format is rather cumbersome to write by hand (my excuse for not always keeping it up to date).