On Demand WebSrc - Source Code Browsing

• What is ``Source Code Browsing''?

  Have you ever thought ``How happy we were if we could browse these goddam source codes on the web browser!'' with tracing some terribly up-breaking sources on numerously opened window terminals? Indeed we had never seen such browsing method, so we planned to develop ``WebSrc'', file converter from an original source code to html style one, to meet such needs.

  Now you can simply try source code browsing on clicking here. You will see the definition of rt_mach_msg which is the real-time IPC function of RT-Mach MK95. If there are unknown keywords, functions or type-definitions (which must be hyper-linked, i.e., underlined) in it, you can click them and browse beyond the keyword.

• What is ``WebSrc''?

  WebSrc is a single program executable from a command line, but has two roles of: Database utility for maintenance of the source code information, and CGI program activated by httpd server.
  • Database utility

    WebSrc works based on a particular database that contains relations between each keyword and file name in which the keyword is defined (i.e., the keyword and the location of its definition). For any source tree, you must prepare such database in advance. Note that all you need is the database instead a fully HTML converted source tree. HTML conversion will be performed on demand only when you issue a CGI request.

  • CGI program

    On receiving a user request in the CGI fashion, WebSrc makes adequate response. For example, in case that the request contains a keyword, WebSrc looks up the keyword in a designated database, and if there is the corresponding tupple, it outputs the source file in the html style. In another case that the request contains only a file name, WebSrc simply finds the source code and outputs similarly.

  The picture below depicts the relationship between elements composing the WebSrc system.

  

• How to generate the database?

  Note that when httpd server activates WebSrc (or its stub CGI program), it can designate only one database. Since database boundary reflects relationship boundary between individual source codes, all of keywords belonging to a particular source tree or the same category should be aggregated to one database.

  In practice, when WebSrc generates a database, the following tupples of information are required:

  KEYWORD₁ LINE₁ FILE₁
  KEYWORD₂ LINE₂ FILE₂
  ...
  KEYWORD_n LINE_n FILE_n

  where KEYWORD is the keyword which will be printed as a clickable link, FILE is the file name in which the keyword is defined, LINE is the beginning line number of the definition part in the file.
  • How to generate such tupples?

    One easy solution is to use ``ctags'', which reasonably produces what we want. It is also recommended since it supports Pascal and FORTRAN as well as C language. Otherwise, you can use another kind of cross referencer, such as ``cxref'', but cxref is C specific and requires a completely arranged source tree.

• How to activate ``WebSrc''?

  In general, WebSrc is activated through its stub CGI program which is called by httpd server and activates WebSrc, adding the common information for the group depending on the stub.

  There are two types of activation: one is issued from WebSrc's html style output, directly identifying the keyword, line number, and file name. Since all of keywords included in the original source file are fully looked up, we can say this is a priori activation in a sense. Another is issued through browser's form input, allowing higher flexibility to the user query.

  • A priori activation example:

    mach_msg_return_t
    rt_mach_msg(msg, option, send_size, rcv_size, rcv_name, timeout, notify)
    	rt_mach_msg_header_t *msg;
    	mach_msg_option_t option;
    	mach_msg_size_t send_size;
    	mach_msg_size_t rcv_size;
    	mach_port_t rcv_name;
    	mach_msg_timeout_t timeout;
    	mach_port_t notify;
    {
    	mach_msg_return_t mr;
    ...
    

  • Query type activation example:

    Please input a keyword, ``rt_mach_msg'' for example, and click the Search button (or press RETURN key). Before long, you will see the same output as you click the a priori keyword ``rt_mach_msg''. Then, click the [Allow partial matching:] Yes button in addition to the present condition, and push the Search button again. This query maybe requires a longer wait than above, but you will obtain more information, that is, other partially matching entries will be listed.

    • Keyword

      • Allow partial matching:
        

        No (fast!)

        Yes (very slow...)

• How to make ``WebSrc''?

  WebSrc is a small C code. You can compile it by only executing ``make prog'' command, then put it to the cgi accessible path, such as ``$(server directory)/cgi-bin''. I hope someone port it to Perl as a script so that there is no need to compile it.

• How to make other files?

  Like WebSrc, other files, such as database, stub, and table of contents, etc. are also made through ``make others''. You only have to edit the Makefile for your configuration like follows:

  ########################################################################
  #
  #	User configurable variables
  #
  ########################################################################
  
  # Default database path
  DBPATH = /export5/apache/cgi-bin/narita
  
  # converter name
  CGI = websrc
  
  # converter path
  CGIPATH = /export5/apache/cgi-bin/narita
  
  # Stub cgi path
  STUBPATH = /export5/apache/cgi-bin/narita
  
  # Stub cgi URL
  STUBURL = /cgi-bin/narita
  
  ########################################################################
  #
  #	RT-Mach
  #
  ########################################################################
  
  # Source tree's origin
  ORIGIN = /usr/src3/RT-Mach/rtmach.RMK95/mk
  
  # database name
  DB = rmk
  
  # Stub cgi name
  STUB = stubRMK
  
  # Searcher URL
  SEARCHERURL = /person/narita/RTMACH.html
  
  # Searcher Title
  SEARCHERTITLE = 'Exploring the RT-Mach MK95 Source Code'
  

  On executing ``make'', there are 6 files generated (note that ``rmk'' is the database's name, here):

  • stubRMK: the stub cgi program for this source tree
  • rmk.files: a complete path list of the whole source tree
  • rmk.table: a complete path list of the whole source tree in the html style
  • rmk.tags: a collection of tags files constructed from rmk.files
  • rmk.dir: tags file database (DBM database)
  • rmk.pag: tags file database, body

  You have to put the stub and database file to the explicitly specified place. Remember that you should not change the stub and database name when you move them to the directory.

• How to create the searcher tag?

  It is responsible for you to create the searcher tag, like this. Searcher tag's fundamental function is to construct a query and send it to cgi stub. The query can be generated through the html FORM tag, GET method. You have to prepare the following input fields:

  • An input field whose name is ``key'', which denotes the keyword.
  • Optionally, an input field whose name is ``partial'', value is ``yes'' or ``no'', each of which selects the partial matching mode, or not.
  • Alternatively, an input field whose name is ``partkey'', which denotes the keyword and automatically selects the partial matching mode.
  • Optionally, an input field whose name is ``file'', which explicitly select the loading file, only when the keyword is not specified.
  • Optionally, an input field whose name is ``db'', which explicitly select the database.

• Let's browse ``WebSrc'' itself!

• Usage of WebSrc

• Ask us

  If you are interested in our WebSrc or have some problems, please ask us your question by e-mail to narita@mt.cs.keio.ac.jp.

• Download: WebSrc 1.05beta

  You can download WebSrc source code on clicking here. All rights reserved. Copyright (C) 1996 by NARITA Tomio (narita@mt.cs.keio.ac.jp).

NARITA Tomio
email: narita@mt.cs.keio.ac.jp
Homepage: http://www.mt.cs.keio.ac.jp/person/narita.html