==============================
APPLY ANY PATCHES TO A RELEASE
==============================

As of 03/28/2026 there are a few updates to apply to the 03/14/2026 8.2.0 release.

... For all OS's, bug fixes for recon-all expert options - note these updates do not change recon-all output ...
bin/recon-all
bin/rca-surfreg
... For Ubuntu24, the expert options update listed above and the addition of the library ...
python/lib/python3.8/site-packages/samseg/gems/gemsbindings.cpython-38-x86_64-linux-gnu.so

To apply these changes download the following script,
https://surfer.nmr.mgh.harvard.edu/pub/dist/freesurfer/8.2.0/fs820_updates.sh

Run the script for the difference OS's as follows:

On MacOS:
$ sudo FREESURFER_HOME=/Applications/freesurfer/8.2.0 bash fs820_updates.sh

On Rocky and CentOS Linux:
$ sudo FREESURFER_HOME=/usr/local/freesurfer/8.2.0-1 bash fs820_updates.sh

On Ubuntu Linux:
$ sudo FREESURFER_HOME=/usr/local/freesurfer/8.2.0 bash fs820_updates.sh

You will be prompted on the command line as to whether or not you want to update each file, including displaying the description of the change(s)listed above.

=============================
SETUP YOUR FREESURFER LICENSE
=============================

Freesurfer commands require a license in order to run.  A "license.txt" file will be emailed to the address you specify when you fill out the registration form at https://surfer.nmr.mgh.harvard.edu/registration.html

While it still works to copy a license.txt file into the freesurfer tree as $FREESURFER/.license in order for the license file to be read, we highly recommend that individual users make use of the FS_LICENSE environment variable for freesurfer commands to read their individual license.txt file.
                                                                                                  
You should always have access to your home directory as setup on a machine when your account is created.  Your home directory is the default destination for the "cd" command with no arguments and always denoted by the value of $HOME in whatever login shell you use.

$ cd
$ pwd
<path to your home directory>
$ cd $HOME
$ pwd
<path to your home directory>

Therefore, if you place the license.txt file in your home directory, then the path to it can always be referenced by $HOME/license.txt.  If you in turn set that path as the value for FS_LICENSE in your shell initialization file, then any freesurfer distribution you set FREESURFER_HOME to point to will in turn be able to find and read your license.txt file.

In $HOME/.bashrc add
export FS_LICENSE=$HOME/license.txt

In $HOME/.cshrc add
setenv FS_LICENSE $HOME/license.txt


=====================================
NEW RECON-ALL BEHAVIOR IN 8.X RELEASE
=====================================

Commands in the 8.X recon-all pipeline have changed compared to previous releases and decrease the amount of time it takes to perform a recon-all on a machine with a single multi-core CPU chip, e.g., a user personal machine that is not a server or in a cluster.

Recon-all performed on subject bert from the tutorial data:
$ recon-all -all -i I50 -s Subj001

Recon-all time with new behavior:
- 1.8 hours on MacMini (darwin_arm64) with M2 chip, 32G RAM, running MacOS Sonoma (14.7.2)
- 2.5 hours on iMac (darwin_x86_64) with Intel Core i9 chip, 32G RAM, running MacOS Ventura (13.7.3)

The reduction in the amount of time it takes to run the pipeline via new python code does however require more memory compared to previous freesurfer releases.  At some point during the 8.X recon-all, ~80G of RAM will be in use.  A machine with efficient memory management can handle this, e.g., total system RAM = 32G with nothing but the recon-all application running directly on the host OS (and not in a virtual machine).  You can revert an 8.X release to the old recon-all behavior by setting the environment variable FS_V8_XOPTS=0 on the recon-all command line, e.g., for the above command,

$ export FS_V8_XOPTS=0 && recon-all -all -i I50 -s Subj001

Reverting recon-all to the old behavior increases the recon-all times on the above machines to 10+ hours.  All recon-all times listed for MacOS are for the case where no other applications have been launched by the user to run on the machine.


===========================
SETUP A MATLAB DISTRIBUTION
===========================

*** IMPORTANT NOTES *** 
- On Linux platforms, the LD_LIBRARY_PATH for the Matlab Runtime environment is incompatible with Freeview, i.e., you will not be able to run Freeview while LD_LIBRARY_PATH is set for Matlab Runtime.
- We do not support a runtime environment newer than MCRv97 as of the 8.2.0 release.
- We do not officially support users linking in their own (licensed) copy of Matlab from outside the freesurfer tree.

Note the location of your Freesurfer installation which is the path used to set FREESURFER_HOME.  For the 8.2.0 release you would set FREESURFER_HOME in a bash (or equivalent shell like zsh) as follows:

Rocky Linux
$ export FREESURFER_HOME=/usr/local/freesurfer/8.2.0-1

Ubuntu Linux
$ export FREESURFER_HOME=/usr/local/freesurfer/8.2.0

MacOS *
$ export FREESURFER_HOME=/Applications/freesurfer/8.2.0

If you are not running 8.2.0, then use the release (or dev) name that corresponds to your install path for the setting of FREESURFER_HOME. Once FREESURFER_HOME is set via the export command in the shell, then run the Matlab Runtime install script.

$ bash
$ sudo FREESURFER_HOME=$FREESURFER_HOME $FREESURFER_HOME/bin/fs_install_mcr R2019b
<output deleted>

... For Linux, the output from the Matlab installer may indicate to set LD_LIBRARY_PATH as follows ... 

$ export LD_LIBRARY_PATH=$FREESURFER_HOME/MCRv97/runtime/glnxa64:$FREESURFER_HOME/MCRv97/bin/glnxa64:$FREESURFER_HOME/MCRv97/sys/os/glnxa64:$FREESURFER_HOME/MCRv97/extern/bin/glnxa64

... For MacOS, the output from the Matlab installer may indicate to set DYLD_LIBRARY_PATH as follows ...

$ export DYLD_LIBRARY_PATH=/Applications/MATLAB/MATLAB_Runtime/v97/runtime/maci64:/Applications/MATLAB/MATLAB_Runtime/v97/sys/os/maci64:/Applications/MATLAB/MATLAB_Runtime/v97/bin/maci64:/Applications/MATLAB/MATLAB_Runtime/v97/bin/maci64/v97/extern/bin/maci64

* On MacOS, a pop-up window may ask to confirm installation of the Matlab Runtime environment under /Applications/MATLAB/MATLAB_Runtime via its package installer; click on the "Next" button to continue.