{smcl}
{* 11nov2005}{...}
{cmd:help adoupdate}
{hline}

{title:Title}

{pstd}
{bf:[R] adoupdate -- Update user-written ado-files}


{phang}
{bf:WARNING:}
This version you have installed of {cmd:adoupdate} is 
work in progress.  Use {cmd:adoupdate} with caution.


{title:Syntax}

{p 8 16 2}
{cmd:adoupdate}
[{it:pkglist}]
[{cmd:,}
{it:options}
]


{p 4 4 2}
where {it:options} are 

{col 8}{it:options}{col 21}description
{col 8}{hline 65}
{col 8}{cmd:update}{col 21}perform update
{col 21}    default is to list packages that have updates,
{col 21}    but not to update them

{col 8}{cmd:all}{col 21}include packages that might have updates
{col 21}    default is to list or update only packages that
{col 21}    are known to have updates 

{col 8}{cmdab:ssc:only}{col 21}check packages obtained only from SSC
{col 21}    default is to check all installed packages

{col 8}{cmd:dir(}{it:dir}{cmd:)}{col 21}check packages installed in {it:dir}
{col 21}    default is to check those installed in {help sysdir:PLUS}

{col 8}{cmd:verbose}{col 21}provide output to help in debugging network problems
{col 8}{hline 65}


{title:Description}

{pstd}
User-written additions to Stata are called packages.
These packages can add remarkable abilities to Stata.
Packages are found and installed using {bf:{help ssc:[R] ssc}}, 
{cmd:findit} in 
{bf:{help search:[R] search}},
and {bf:{help net:[R] net}}.

{pstd}
User-written packages are updated by their developers just as official 
Stata software is updated by StataCorp.  

{pstd}
To determine whether your official Stata software is up to date, and to 
update it if not, you use {bf:{help update:[R] update}}.

{pstd} 
To determine whether your user-written additions are up to date, and to 
update them if not, you use this command, {cmd:adoupdate}.


{title:Options}

{phang}
{cmd:update} specifies that packages with updates are to be updated.
    The default is simply to list the packages that could be updated
    without actually performing the update.

{pmore}
    The first time you {cmd:adoupdate}, do not specify this option.  Once you
    see {cmd:adoupdate} work, you will be more comfortable with it.  Then
    type

		. {cmd:adoupdate, update}

{pmore}
    The packages that can be updated will be listed and updated.

{phang}
{cmd:all} is rarely specified.  Sometimes, {cmd:adoupdate} cannot determine
    whether a package you previously installed has been updated.
    {cmd:adoupdate} can determine that the package is still available over the
    web, but it is unsure about whether it has changed.  Usually, the package
    has not changed, but if you want to be certain you are using the latest
    version, the only thing to do is to reinstall from the source.

{pmore}
    Specifying {cmd:all} does this.  Typing 

		. {cmd:adoupdate, all}
    
{pmore}
    adds such packages to the displayed list as needing updating but, 
    of course, does not update them.  Typing

		. {cmd:adoupdate, update all}

{pmore}
    lists such packages and updates them.
    
{phang}
{cmd:ssconly} is a popular option.  Many packages are available from the SSC
    (Statistical Component Archive) -- often called the Boston College Archive
    -- that is provided by {browse "http://www.repec.org"}.  Many users find
    most of what they want there.

{pmore}
    {cmd:ssconly} specifies that {cmd:adoupdate} check packages 
    obtained only from that source.  That is popular to do because that 
    source always provides distribution dates, and so {cmd:adoupdate} 
    can be certain as to whether an update exists.

{phang}
{cmd:dir(}{it:dir}{cmd:)}
     specifies which installed packages are to be checked.  The default 
     is {cmd:dir(PLUS)}, and that is probably correct.  If you are 
     responsible for maintaining a large system, however, you may 
     have previously installed packages in {cmd:dir(SITE)}, where they 
     are shared across users.

{phang}
{cmd:verbose} is specified when you suspect network problems.  It provides
    more detailed output that may help you diagnose the problem.


{title:Remarks}

{pstd}
Do not confuse {cmd:adoupdate} with {cmd:update}.  Use {cmd:adoupdate} to 
update user-written files.  Use {cmd:update} to update the components 
(including ado-files) of the official Stata software.
To use either command, you must be connected to the Internet.

{pstd}
Remarks are presented under the headings

	{bf:Using adoupdate}
	{bf:Possible problems the first time you run adoupdate, and their solutions}
	{bf:Notes for developers}


{title:Using adoupdate}

{pstd}
The first time you try {cmd:adoupdate}, type 

	. {cmd:adoupdate}

{pstd}
That is, do not specify the update option.  {cmd:adoupdate} without 
{cmd:update} produces a written report.  The first time you run 
{cmd:adoupdate}, you may see messages such as 

	. {cmd:adoupdate}
	  (note:  package utx was installed more than once; older copy removed)
	  {it:(remaining output omitted)}

{pstd}
It is easy to have packages installed multiple times; {cmd:adoupdate} cleans 
that up.

{pstd}
The second time you run {cmd:adoupdate}, pick one package to update.
Say the report indicates that package st0008 has an update available.
Type

	. {cmd:adoupdate st0008, update}

{pstd}
You can specify one or many packages following the {cmd:adoupdate} command.
You can even use wildcards such as {cmd:st*} to mean all packages that 
start with st or {cmd:st*8} to mean all packages that start with st and 
end with 8.  You can do that with or without the {cmd:update} option.

{pstd}
Finally, you can let {cmd:adoupdate} update all your user-written additions:

	. {cmd:adoupdate, update}


{title:Possible problems the first time you run adoupdate, and their solutions}


    {title:Problem 1:  Lots of duplicates and takes a long time to run}

{pstd}
The first time you run {cmd:adoupdate}, you might get many duplicate
messages:

	. {cmd:adoupdate}
	  (note: package ___ installed more than once; older copy removed)
	  (note: package ___ installed more than once; older copy removed)
	  (note: package ___ installed more than once; older copy removed)
	  ...
	  (note: package ___ installed more than once; older copy removed)
	  {it:(remaining output omitted)}

{pstd}
Some users have hundreds of duplicates.
You might even see the same package name repeated more than once, such as 

	  (note: package stylus installed more than once; older copy removed)
	  (note: package stylus installed more than once; older copy removed)

{pstd} 
That just means the package was duplicated twice.

{pstd} 
Stata is tolerant of duplicates and you did nothing wrong when you previously
installed and updated packages.  {cmd:adoupdate}, however, needs
the duplicates removed, mainly so that it does not keep checking the 
same files.

{phang} 
{it:Solution:}{break}
    Just let {cmd:adoupdate} run.  {cmd:adoupdate} will run faster next time,
    when there are no duplicates or just a few.


    {title:Problem 2:  Package needs updating, and updating, and updating, ...}

{pstd}
You run 

	. {cmd:adoupdate, update}

{pstd}
and you are told a package -- let's call it
{cmd:stylus} -- needs updating, {cmd:adoupdate} updates the
package, and yet, if you were immediately to rerun {cmd:adoupdate}, 
the package needs updating again!

{pstd}
What has happened is that you have an up-to-date version of 
{cmd:stylus}, but you installed it before the server adopted
recording distribution dates, which is how {cmd:adoupdate} tells whether a
package is up to date.

{phang}
{it:Solution 1:}{break}
     Let's assume you obtained package {cmd:stylus} from SSC.
     If you obtained it from some other source, see solution 2 below.

{pmore}
    First, verify you have the problem:

	    . {cmd:adoupdate stylus}
	    (output appears saying stylus needs updating)

	    . {cmd:ssc install stylus, replace}
	    checking stylus consistency and verifying not already installed...
	    all files exist and are up to date.

{pmore}
    To summarize:  {cmd:adoupdate} says the package needs updating.  You
    update the package by hand, and {cmd:ssc} says it is up to date.  If
    {cmd:ssc} updates the package on the other hand, all is now well and you
    can stop here.  Assuming you get the "all files are up to date" message, 
    type

	    . {cmd:ssc uninstall stylus}

	    . {cmd:ssc install stylus}

{pmore}
    That fixes the problem.


{phang}
{it:Solution 2:}{break}
    You did not obtain {cmd:stylus} from SSC; find out where you did
    obtain it from:

	    . {cmd:ado dir stylus}
	    [21] package stylus from http://www...
            {it:(remaining output omitted)}

{pmore}
See the first line of the output, the part that reads "from http://www...."?
Make a note of the URL.

{pmore}
Now, verify you have the problem:

	    . {cmd:adoupdate stylus}
	    (output appears saying stylus needs updating)

	    . {cmd:net from http://www...}

	    . {cmd:net install stylus, replace}
	    checking stylus consistency and verifying not already installed...
	    all files exist and are up to date.

{pmore}
    To summarize:  {cmd:adoupdate} says the package needs updating.  You
    update the package by hand, and {cmd:net install} says it is up to date.
    If {cmd:net install} updates the package on the other hand, all is now
    well and you can stop here.  Assuming you get the
    "all files are up to date" message, type


	    . {cmd:ado uninstall stylus}

	    . {cmd:net install stylus}

{pmore}
    That fixes the problem.


{title:Notes for developers}

{pstd}
{cmd:adoupdate} reports whether an installed package is up to date by 
comparing the distribution date of the package installed with the 
package available over the web.

{pstd}
If you are distributing software, include the line

	{cmd:d Distribution-Date:}  {it:date}

{pstd}
somewhere in your {cmd:.pkg} file.  Capitalization of 
{cmd:Distribution-Date} does not matter, but include the hyphen and the colon
just as shown.  Code the
date in either of two formats:

	   all numeric:  {it:yyyymmdd},  for example, {cmd:20050508}

	Stata standard:  {it:ddMONyyyy}, for example, {cmd:8may2005}


{title:Saved results}

{pstd}
{cmd:adoupdate} saves in {cmd:r(pkglist)} a space-separated list of 
package names 
that 
need updating (option {cmd:update} not specified) or 
that were updated (option {cmd:update} specified).


{title:Also see}

{psee}
Manual:  {bf:[R] adoupdate} (forthcoming)

{psee}
Online:  
{bf:{help ssc:[R] ssc}},
{bf:{help search:[R] search}},
{bf:{help net:[R] net}},
{bf:{help update:[R] update}}
{p_end}