[80582] branches/gsoc11-statistics
derek at macports.org
derek at macports.org
Fri Jul 15 06:24:20 PDT 2011
Revision: 80582
http://trac.macports.org/changeset/80582
Author: derek at macports.org
Date: 2011-07-15 06:24:19 -0700 (Fri, 15 Jul 2011)
Log Message:
-----------
Added impl.tex - a document describing the implementation of the statistics collection project for GSoC 2011.
- Currently it describes what has been implemented in MacPorts base
Added Paths:
-----------
branches/gsoc11-statistics/docs/
branches/gsoc11-statistics/docs/implementation/
branches/gsoc11-statistics/docs/implementation/impl.tex
Added: branches/gsoc11-statistics/docs/implementation/impl.tex
===================================================================
--- branches/gsoc11-statistics/docs/implementation/impl.tex (rev 0)
+++ branches/gsoc11-statistics/docs/implementation/impl.tex 2011-07-15 13:24:19 UTC (rev 80582)
@@ -0,0 +1,190 @@
+\documentclass[10pt]{article}
+\usepackage{fullpage}
+
+
+\title{MacPorts Statistics - Google Summer of Code 2011}
+\author{ Derek Ingrouville - derek at macports.org }
+
+\date{\today}
+
+\begin{document}
+
+\maketitle
+
+\setlength{\parskip}{0.3cm}
+
+\section{Client Side - MacPorts Base}
+
+\subsection{Install}
+
+In order to automatically submit data at regular intervals some small changes had to be made to the installation process. These changes include installing a script which handles data submissions \texttt{submitstats.sh}, configuring \texttt{launchd} to regularly run \texttt{submitstats.sh}, and generating a unique identifier for the user submitting data.
+
+\subsubsection{Makefile.in}
+\begin{itemize}
+ \item Install \texttt{submitstats.sh} to \texttt{\$(DESTDIR)\${datadir}/macports/}
+ \item Run \texttt{setupstats.sh}
+\end{itemize}
+
+\subsubsection{configure.ac}
+
+Generate a universally unique identifier to identify this MacPorts installation. The UUID is generated by \texttt{uuidgen} and stored in the variable \texttt{STATS\_UUID}
+
+\subsubsection{Scripts}
+\begin{itemize}
+\item \texttt{setupstats.sh}
+
+This script is responsible for generating and installing the file \texttt{org.stats.macports.plist}. This plist is used by \texttt{launchd} to regularly run \texttt{submitstats.sh}.
+
+The script takes two arguments
+\begin{enumerate}
+ \item The path to the script that \texttt{launchd} should execute
+ \item The path to the MacPorts configuration file \texttt{macports.conf}
+\end{enumerate}
+
+It will execute the script once a week. The day of the week, hour and minute are determined as follows: \newline
+
+
+\textbf{Weekday:} The day of the week is determined by the machine's hardware UUID modulo 7. This is to help ensure that submissions are roughly evenly distributed throughout the week. \newline
+\textbf{Hour: } The hour that \texttt{submitstats.sh} was executed. \newline
+\textbf{Minute:} The minute that \texttt{submitstats.sh} was executed. \newline
+
+The plist is installed to \texttt{/Library/LaunchAgents/org.macports.stats.plist} and then loaded by \texttt{launchctl}
+
+\item \texttt{submitstats.sh}
+
+This script has two responsibilities
+\begin{enumerate}
+ \item Check if a user is participating.
+ \item Submit data only if the user if participating
+\end{enumerate}
+
+It takes one parameter, the path to \texttt{macports.conf}.
+
+To determine if a user is participating it checks if the variable \texttt{stats\_participate} is set to \texttt{yes}. If it is, then \texttt{port stats submit} is executed. If the user is not participating then the script exits.
+
+The reason this script exists is to have a lightweight tool to check if a user is participating before running \texttt{port}. This script will be executed once a week for every user, regardless of whether or not they are participating.
+
+\end{itemize}
+
+\subsection{Configuration}
+
+Added several variables to \texttt{macports.conf.in} and appropriate descriptions to \texttt{macports.conf.5}.
+
+\begin{itemize}
+ \item \texttt{stats\_participate}
+
+ This indicates whether or not a user has chosen to opt-in and share their data. Its value is either \texttt{yes} or \texttt{no}
+
+ \item \texttt{stats\_url}
+
+ This is the url where data should be submitted.
+
+ \item \texttt{stats\_id}
+
+ This is the UUID used for submissions. It is initially set to value of the autoconf variable \texttt{@STATS\_UUID@}.
+\end{itemize}
+
+\subsection{Changes to macports1.0/macports.tcl}
+\begin{itemize}
+ \item New Globals
+
+ Added globals \texttt{stats\_participate}, \texttt{stats\_url}, \texttt{stats\_id} that correspond to configuration options. \newline
+ Added deferred global \texttt{gccversion}
+ \item \texttt{gcc} version check
+
+ Added proc setgccinfo that is called the first time \texttt{gccversion} is read.
+\end{itemize}
+
+\subsection{Changes to pextlib1.0/curl.c - CurlPostCmd()}
+
+Added CurlPostCmd function. This takes two Tcl parameters, the post data and the url.
+
+Example usage is
+\begin{verbatim}
+ curl post "project=macports" $url
+\end{verbatim}
+
+\subsection{The \texttt{port stats} action}
+\texttt{port stats} gathers lists of all active and inactive ports as well as relevant system information. It no subaction is given \texttt{port stats} prints the system information to \texttt{stdout}.
+
+If the \texttt{submit} subaction is given then it will encode all the collected data as a \texttt{JSON} object. It then submits this via HTTP POST to a server specified in \texttt{macports.conf}.
+
+\texttt{JSON} encoding is done though sub-procedures contained inside the procedure for the \texttt{port stats} action.
+
+\subsection{Changes to port/port-help.tcl}
+TODO
+
+\section{Data Format}
+
+Transmitted data is encoded as a JSON object with four fields.
+
+\begin{verbatim}
+ {
+ "id": "...",
+ "os": {
+ ...
+ },
+ "active_ports": [
+ {...},
+ ...
+ {...}
+ ],
+ "inactive_ports": [
+ {...},
+ ...
+ {...}
+ ]
+ }
+\end{verbatim}
+
+\begin{enumerate}
+ \item id
+
+ This is a string containing the user's UUID.
+
+ \item os
+
+ This is a JSON object containing information about the user's system.
+
+ \begin{verbatim}
+ "os": {
+ "macports_version": "1.9.99",
+ "osx_version": "10.6",
+ "os_arch": "i386",
+ "os_platform": "darwin",
+ "build_arch": "x86_64",
+ "gcc_version": "4.2.1",
+ "xcode_version": "4.0"
+ }
+ \end{verbatim}
+
+ \item active\_ports
+
+ This is an array of json objects. Each object represents a single port.
+
+ \begin{verbatim}
+ "active_ports": [
+ {
+ "name": "aalib",
+ "version": "1.4rc5_4"
+ },
+ {
+ "variants": "nonls +",
+ "name": "aspell",
+ "version": "0.60.6_4"
+ }
+ ]
+ \end{verbatim}
+
+ \item inactive\_ports
+
+ This is the same as active\_ports except that port objects represent installed inactive ports.
+\end{enumerate}
+
+\section{Server Side - Ruby on Rails}
+TODO
+
+
+
+
+\end{document}
\ No newline at end of file
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/macports-changes/attachments/20110715/c5905c57/attachment.html>
More information about the macports-changes
mailing list