Suporte ao Linux
A partir da versão 71, o Engine passou a dar suporte ao Linux em caráter experimental. Apesar de ainda estar em desenvolvimento, a versão Linux do Engine é considerada estável e apta a ser utilizada em ambientes de produção, desde que consideradas as restrições e recomendações de uso descritas neste documento.
No Linux, o Engine é um aplicativo console que deve preferencialmente ser instalado como serviço utilizando o systemd. Por não possuir uma interface gráfica, não há hoje uma forma de realizar a depuração de códigos JavaScript em ambientes Linux, sendo necessário o uso da versão Windows para esse fim. O uso de logs pode ser necessário para diagnosticar eventuais diferenças de comportamento entre as versões Windows e Linux do Engine. Essa limitação deve ser eliminada no futuro, quando for implementada a depuração remota de códigos na extensão “Engine DevTools” do VSCode.
É importante observar que o nível de suporte dado ao Linux na plataforma, que consiste do aplicativo Engine, do Web Framework e dos módulos “Administração do sistema” e “Desenvolvimento”, não se aplica a todos os módulos do sistema, em especial às customizações existentes. O sistema está sendo revisto gradualmente para suportar o Linux. O uso do Engine em servidores Linux em ambientes de produção deve ocorrer apenas após um processo de homologação que inclua testes extensivos nos processos e relatórios que serão utilizados, incluindo as eventuais customizações desses processos.
Distribuições suportadas
Atualmente o Engine não é fornecido via sistemas de instalação nativos das distribuições Linux. Ele deve ser instalado em um diretório com permissão de escrita seguindo as orientações contidas na página de instalação do sistema /install.
No desenvolvimento e na homologação da versão Linux do Engine são utilizadas as distribuições “Ubuntu 24.04 LTS” e “Debian 12”. O uso dessas distribuições nesta fase inicial do suporte ao Linux é recomendado para evitar eventuais incompatibilidades ainda desconhecidas, decorrentes das diferenças existentes entre as distribuições Linux. Apesar dessa recomendação, não há problema conhecido que impeça o uso de outras distribuições, sendo necessário apenas que elas atendam os requisitos abaixo:
- A versão da
GNU C Library (glibc) deve ser a 2.39
ou superior. Para verificar a versão da glibc, utilize o comando
ldd --version
. - As variáveis de ambiente
LANG
eLC_*
devem estar configuradas com um locale que utilize codificação UTF-8. - A instalação do Engine em estações clientes que acessem o servidor utilizando o protocolo HTTPS requer a biblioteca “libssl1.1”. Essa biblioteca normalmente está disponível em um pacote de mesmo nome nas distribuições Linux.
Uma diferença importante entre a glibc do Linux e o runtime C do Windows é a compatibilidade com versões antigas do sistema operacional. Enquanto ambos os runtimes garantem que um aplicativo compilado para uma versão de um runtime funcione em versões futuras dele, a glibc não dá garantia de que um aplicativo compilado para uma versão nova funcione em versões antigas de uma distribuição Linux. Por esse motivo, versões futuras do Engine que necessitem da atualização da glibc podem requerer a atualização da versão do sistema operacional.
A atualização da versão mínima da glibc requerida pelo Engine não é frequente e, quando ocorrer, será indicada como uma alteração de alto impacto nas notas de liberação. Essa nota deve ser observada com atenção, pois o Engine pode deixar de funcionar logo após a atualização se a versão da glibc do sistema operacional Linux utilizado não satisfizer a versão mínima exigida. O impacto dessas atualizações deve ser reduzido no futuro por meio da distribuição do Engine em imagens de containers.
Diferenças de comportamento
Algumas diferenças de comportamento entre as versões Windows e Linux do Engine são esperadas e devem ser tratadas adequadamente pelos códigos JavaScript desenvolvidos na plataforma. Abaixo são relacionadas as principais delas.
Classes não suportadas no Linux
As classes ComObject
, Spool
e HtmlPrinter
dependem de conceitos ou recursos específicos
do sistema operacional Windows e elas não são suportadas na versão Linux do Engine. Códigos
que façam uso dessas classes devem tratar a possibilidade delas não existirem no escopo global
(
globalThis
)
ou devem verificar a plataforma em execução por meio da propriedade
engine.platform
antes da sua utilização.
Classe HtmlToPdf requer a instalação do componente wkhtmltopdf
Diferentemente da versão Windows, o componente
wkhtmltopdf não é
distribuído e instalado automaticamente pelo sistema no Linux, sendo necessário que ele
esteja disponível no PATH para que a classe
HtmlToPdf
possa ser utilizada.
Este componente normalmente é distribuído como um pacote de mesmo nome. Também é recomendado que seja instalada a fonte “Roboto” que é a fonte padrão do sistema. Nas distribuições Debian e Ubuntu, o comando abaixo pode ser utilizado para instalar essas dependências:
sudo apt install wkhtmltopdf fonts-roboto
Delimitador de caminhos do sistema de arquivos
No Windows, por padrão, é utilizada a barra invertida ('\'
) para separar os diretórios e arquivos
em caminhos de arquivos, enquanto no Linux é utilizada a barra normal ('/'
). Para tratar essa
diferença de comportamento, é recomendado o uso da função
File.pathAppend()
e da propriedade
File.pathSeparator
em vez de delimitadores fixos em strings literais.
Também é importante observar que no Linux não há o conceito de letra de unidade e os caminhos
absolutos sempre iniciam no diretório “/”. Processos que trabalhem com arquivos devem
preferencialmente utilizar caminhos relativos ao diretório de trabalho do Engine
engine.dataDir
.
Processos que utilizem caminhos informados pelo usuário devem verificar se o caminho está no
formato adequado considerando o sistema operacional do Engine no qual ele será utilizado.
Observação: o delimitador '/'
também é suportado no Windows, no entanto, não é recomendado
o seu uso misturado com delimitador padrão '\'
em um mesmo caminho. Os dois exemplos abaixo
são equivalentes no Windows:
File.stringFromFile('c:/tmp/test.txt');
File.stringFromFile('c:\\tmp\\test.txt');
Controle de timeout da classe SerialPort
O controle de timeout das portas seriais no Linux é mais restrito que no Windows. Por esse motivo,
as propriedades readIntervalTimeout
, readTotalTimeoutMultiplier
, readTotalTimeoutConstant
,
writeIntervalTimeout
, writeTotalTimeoutMultiplier
e writeTotalTimeoutConstant
da classe
SerialPort
não são suportadas no Linux.
Para garantir a compatibilidade com ambos os sistemas operacionais, devem ser utilizadas apenas
as propriedades readTimeout
e writeTimeout
.
Codificação padrão de arquivos texto
Com o objetivo de preservar o funcionamento dos códigos desenvolvidos na plataforma, a codificação padrão do sistema continua a ser “windows-1252” na versão Linux do Engine. Ela é usada quando uma codificação não é explicitamente informada nas APIs de manipulação de arquivos.
É recomendado que os códigos novos adotem a codificação “utf-8” sempre que for possível, pois além de ser a codificação padrão no Linux, ela também é adotada pela maiorias das aplicações modernas do Windows na manipulação de arquivos textuais. Códigos antigos devem ser gradualmente revistos para suportar a codificação “utf-8”, melhorando a interoperabilidade do sistema com outras aplicações.
// Leitura e abertura do arquivo utilizando a codificação "windows-1252"
File.stringFromFile('test.txt');
const file = new File('test.txt', 'openRead');
// Leitura e abertura do arquivo utilizando a codificação "utf-8"
File.stringFromFile('test.txt', 'utf-8');
const file = new File('test.txt', 'openRead', 'utf-8');