How do I fix a bug in Mata?

When you review the official source, you might spot a bug. If you do, naturally, you will report it to us (see Stata Technical Services). Then we can fix the problem and issue an update.

In the meantime, you might want to fix the bug yourself.

What follows is technical. You may want to skip reading it until you need it.

If you wish to continue, say three times to yourself, “Mata’s official code does not have bugs.” Now look again at what you thought was a bug. It has probably vanished. We find that works for us in most cases; what we thought was a bug was caused by our own confusion. Nevertheless, bugs do occur, and sometimes you cannot wait for the official fix. In that case, perform the following steps:

1. Make a copy of the .mata file in the current directory. We will pretend the problem is with official function helloworld(), the source code of which appears in file helloworld.mata:

   . copysource helloworld.mata

   copysource is not documented in the manuals, but online help is available; see help copysource.
   
   
2. Edit the copy of the file. You could use Stata's doedit command:

   . doedit helloworld.mata

3. Clear Mata and compile the updated source code:

   . mata: mata clear . do helloworld.mata

4. Save the compiled source in a .mo file:

   . mata: mata mosave helloworld()

   mata mosave is documented in [M-3] mata mosave. The above will save helloworld.mo in the current directory. You may prefer to save it in your personal directory:

   . mata: mata mosave helloworld(), dir(PERSONAL)

5. Tell Mata to look for .mo files before searching its libraries:

   . mata: mata set matamofirst on

6. Test your fix. Repeat steps 2, 3, 4, and 6 as necessary. You do not need to repeat step 5. In step 4, specify mata mosave's replace option.

       . mata:  mata set matamofirst on, permanently

Be careful about that, however, because now, when StataCorp fixes helloworld(), and you install the update, Mata will continue searching the .mo files first. You will end up using your version and not the the updated version in the library. You will need to remember to

       . mata:  mata set matamofirst off, permanently

after installing the official update.

At that point, you will want to erase helloworld.mo, too, but, if you forget, it will not matter because Mata will be back to searching its libraries first.

Function helloworld() is actually part of official Mata:

       . helloworld()
         hello, world

If you need to fix a bug, we suggest you practice modifying helloworld.mata before working on a real file.