- Make sure that the executables you need are in your path (e.g., R, Julia, Python)
- Backward compatibility: runcode involves many components, including the LaTeX compiler, R, Julia, Python, etc. We try to make it as backward compatible as possible, but this is not always possible since it depends on backward compatibility of individual components. We recommend using the latest stable version of each component.
- Package conflicts: runcode uses a small number of contributed LaTeX packages (see the documentation). These packages work well together, and we are not aware of any conflicts. However, users are very likely to use other packages and it may happen that these packages have definitions which conflict with one of the packages that runcode relies on. We are currently not aware of any specific example, but in general we find that when such conflict between packages arises, stackexchange is an excellent place to find a solution or a workaround.
- Port conflict (server-mode): if you are using runcode in its server-mode, keep in mind that the IP port is per-project. If you are working on multiple projects at the same time, just use a different port number for each one. If you see a warning that the server is already running, check that your config file points to the project-specific port. If the wrong port is used you may get errors when trying to access undefined variables or functions, or worse – you may get no error because the variables/functions are defined but are not what you assume them to be.
- Forking on Windows: the talk2stat package has an option to run the server in the background by forking a child process. This works transparently on Linux and Mac, but on Windows you would get an error:
AttributeError: module 'os' has no attribute 'fork'
The reason for the error is that talk2stat relies on two UNIX-based functions, namely, fork and spawn. However, Windows 10 users can still use talk2stat, thanks to the 'Windows Subsystem for Linux' app which is freely available from the MicroSoft Store. Detailed installation instructions are available here.
It is convenient to use the Windows Terminal in order to access the Linux subsystem (e.g. Ubuntu 20.04 LTS). Once all the installation steps are complete, open the Windows Terminal and access your Linux subsystem. When you use it for the first time, you have to update the operating system, and install a few components:
sudo apt update
sudo apt install python3
sudo apt install python3-pip
sudo apt install r-base
pip3 install talk2stat
Now you have two operating systems on your computer - Windows 10, and a Linux subsystem. The two have access to the same resources which talk2stat uses, namely, the file system and TCP/IP interface. This means that a client used on the Windows10 side can communicate with a server which runs on the Linux side. Using the Windows Terminal, start the talk2stat server on the Linux subsystem (per the instructions in the Usage section). Note that the client functionality of talk2stat does not require the fork and spawn functions, so it can be used from any application on the Windows 10 machine. Note, however, that WSL can’t share executables (e.g. python/R/Julia) with the host Windows system, so in order to use talk2stat, these applications as well as any required packages have to be installed on the WSL. - Interactive commands: note that runcode connects to a statistical tool and emulates an interactive session, which means that it expects the prompt from the program in order to detect the completion of an operation. Therefore, commands which do not return a prompt must be avoided. For example, in R we may want to get help on a function (say, ls) by using “?ls”. R shows one screen at a time and the user must scroll down to get the prompt. Such command will cause runcode to hang. There is a built-in timeout to prevent an infinite wait, but such commands must be avoided.
- Log files: runcode keeps a log file in the project directory (one for each statistical language used by the author). If an error occurs or the output seen in the pdf file seems incorrect, these log files should contain useful clues. Furthermore, the project’s log file, generated by pdflatex, will also contain useful hints. For example, if a connection to the server is refused, or if R/Julia/Matlab reported some syntax error, it will be sent to stderr, and pdflatex will include them in the log file. Finally, runcode keeps intermediate files (code and output) in the project’s tmp directory. These files are not deleted automatically by runcode since they may be used for cache, but are also useful for debugging when necessary).