From Notes

Jump to: navigation, search


2010 HFOSS Summer Institute @ Wesleyan University: Tutorials

07 June: Documentation

  1. Developer documentation
    1. Design/implementation documentation: high-level view; architecture/control model; design choices.
    2. Code documentation: class descriptions, function/method specifications.
  2. User documentation
    1. User manuals, guides.
  3. Other documentation
    1. Installation guides, contributors, etc.
  4. Formats and tools
    1. Standalone documents: text, OpenDocument (ODT), (La)TeX, reStructuredText, Markdown.
    2. Code documentation: Javadoc, Pydoc, Epydoc, Doxygen.
  5. Our documentation plan.
    1. Standalone documents: write using reStructuredText, and keep these documents in a doc subdirectory that lives at the top level of your project code directory. Rationale:
      1. A plain-text markup language is much easier for everyone than ODT or LaTeX.
      2. Why not Markdown? It looks like reStructuredText has a more generous collection of output formats, but otherwise there isn't a compelling reason---this is just an executive decision.
    2. Code documentation: document all new Python code with the Epytext markup language; document all new C/C++ code with Doxygen markup. Rationale:
      1. Why Epytext instead of reStructuredText? Although the latter seems to have made it into various Python Enhancement Proposals, I like Epytext's way of handling the components of class and function specification.
      2. Why Epytext instead of Doxygen? The latter doesn't seem to have things like type tags, presumably because it is geared toward compile-time typed languages like C/C++.
      3. Why Doxygen? Because it's the only one I know of, and apparently Dasher is already (partly) documented with it.
    3. Document existing functions/classes that need documentation in order for us to use them.

15 June: Testing

The testing spectrum: unit-testing---integration testing.

  1. Unit testing.
    1. Small units of functionality; methods/functions.
    2. Not always possible to test individual components in isolation.
    3. Test against *specification*.
    4. The "right way" to write:
      1. Write specification.
      2. Write tests.
      3. Write code.
      4. Test.
      5. Until tests pass, repeat from (3).
  2. Integration testing.
    1. Test interaction of components.
    2. Test components in the large, including database.
    3. UI testing?
  3. Miscellany.
    1. Regression testing: prevent re-introduction of bugs.
    2. Test fixtures.
    3. Mock objects: fake HTTP requests, databases, etc.
    4. Testing space: expected, boundary, error inputs.
  4. Tools: automation is critical!
    1. Java: Junit.
    2. Python: Doctest, Pyunit (Python unittest module), Django testing.
    3. C/C++: Google Test?
  5. A short example with unittest: stack.py and stack_tests.py.
  6. Our testing plan.
    1. Unit tests for all new code.
    2. Integration tests as feasible.
    3. Tests need minimal documentation.
      1. Make clear what functionality is being tested and what kinds of inputs are being used (normal, boundary [specify], error [specify].

06 July: Open-source and free software

(This outline is adapted from the talk given by Ralph Morelli at the HFOSS 2010 Faculty Workshop.)

  1. Free/Libre Software and Open Source Software Movements.
    1. Two big players: The Free Software Foundation and The Open Source Initiative.
    2. The beginning of the free software movement: Richard Stallman, The GNU Manifesto, 1983.
    3. The Open Source Definition (and manifesto).
    4. Stallman's response: Why 'open source' misses the point of free software, 2009.
    5. Suggested Reading: Karl Fogel, What is free software, 2005.
  2. F/LOSS software in the world (take these usage shares with a big grain of salt).
    1. Web servers: Netcraft usage share.
    2. Web browsers Wikipedia usage share.
    3. Operating systems Wikipedia usage share.
  3. F/LOSS Licenses.
    1. Copyrights and patents.
    2. Free software licenses and FSF license categories.
    3. Open-source licenses.
    4. copyleft, and compatibility.
    5. Comprehension check: the Modified BSD license allows derivative works to be licensed so that they cannot be redistributed; so how is it that it is compatible with the GPL? If a project contains some components that are licensed under the Modified BSD license and some that are licensed under the GPL, what can we say about the license for the entire project?
    6. Suggested Reading: K. Fogel, Choosing a license
  4. Other rights (non-)preservation.
    1. Public domain, shareware, and freeware.
    2. Creative Commons.

12 July: Java Web Applications

  1. Servlets and JSPs: PDF notes.
  2. Databases and JDBC: PDF notes.
  3. A simple webapp: Petstore. This is not a particularly good web application; some of the servlet source code refers directly to JSPs rather than resources, and we should be using different doGet and doPost implementations to handle, e.g., an initial request to load the authentication page vs. authentication information being supplied. It also needs an ant build file.
  4. Build process: ant.
  5. Webservers/containers: tomcat. Configuring tomcat for multiple users takes a little bit of care, because we want to be sure that all everyone can run Tomcat without interfering with each other. Here is what you need to do to set things up:
    1. Create a directory named apache-tomcat and the following subdirectories: conf, logs, temp, webapps, and work (we'll refer to apache-tomcat as LOCAL_TOMCAT_HOME from now on).
    2. Copy $TOMCAT_HOME/conf/server.xml, $TOMCAT_HOME/conf/web.xml, and $TOMCAT_HOME/conf/tomcat-users.xml to your conf directory, where TOMCAT_HOME points to the tomcat installation directory (on marlow, this is probably something like /opt/apache-tomcat-XXX). If you want access to the web applications that come with the Tomcat installation, then copy everything in $TOMCAT_HOME/webapps to $LOCAL_TOMCAT_HOME/webapps.
    3. Edit server.xml as follows. First find the Server element, which binds to port 8005 by default; it looks something like:
      <Server port="8005" shutdown="SHUTDOWN">

      Change 8005 to a port that nobody else uses (e.g., 12344). Then search for the string 8080; it should appear in a block that looks like:

      <Connector port="8080" protocol="HTTP/1.1" 
          redirectPort="8443" />

      Change the port number to something that nobody else is using and that also differs from the Server port (e.g., 12345). For safety's sake, you should also add the address attribute so that connections can only be made from the local host. So, when you are done, this block should look like:

      <Connector port="12345" protocol="HTTP/1.1"
          redirectPort="8443" />

      I also recommend commenting out any other Connector stanzas unless you know that you need them.

    4. Edit tomcat-users.xml to add a better username and password to the manager account.
    5. Edit your $HOME/.bashrc to set the following environment variable:

    You can now start and stop Tomcat with the commands $TOMCAT_HOME/bin/startup.sh and $TOMCAT_HOME/bin/shutdown.sh. When you install web applications, be sure to install them in the $LOCAL_TOMCAT_HOME/webapps.

Personal tools
NSF K-12