A forma mais simples de instalar novas definições de estruturas é usar o suporte incorporado do KNewStuff no Okteta. Para instalar uma estrutura existente, abra a janela de configuração da ferramenta de Estruturas. Aí, selecione a página de Gerenciamento de estruturas e pressione no botão Obter estruturas novas.... A janela que aparecerá permite-lhe então instalar ou desinstalar estruturas.

A ferramenta de Estruturas procura pelas descrições de estruturas na subpasta okteta/structures/ da pasta pessoal do usuário para os dados dos aplicativos (descubra-a com o comando qtpaths --paths LocalGenericoDeDados). Talvez você precise criar essa pasta, caso ainda não tenha nenhuma definição de estrutura instalada.

Existem dois arquivos para cada definição de estrutura. Um arquivo para a definição em si e um arquivo .desktop para os metadados (autor, versão, etc).

Nessa pasta, existe uma subpasta para cada definição de estruturas, a qual contém tanto o arquivo .desktop como o .osd ou o main.jspara essa definição.

Por exemplo, com a pasta de dados dos aplicativos qtpaths --paths LocalGenericoDeDados e com uma definição de estrutura chamada EstruturaExemplo, existe a pasta okteta/structures/EstruturaExemplo, que contém um arquivo EstruturaExemplo.desktop e um arquivo EstruturaExemplo.osd.

Após ter instalado uma nova definição de estruturas, você poderá ter que reiniciar o Okteta antes de poder usá-lo. Após ter reiniciado o Okteta, abra a janela de configurações da ferramenta de Estruturas. Nela, selecione a página de Gerenciamento das estruturas e certifique-se que a definição da estrutura relevante é assinalada. Depois, mude para a página Estruturas e certifique-se de que o elemento desejado está listado no lado direito.

Nosso arquivo de metadados se parece com isto:

        [Desktop Entry]
        Icon=arrow-up❶
        Type=Service
        ServiceTypes=KPluginInfo

        Name=Estrutura simples de teste
        Comment=Uma estrutura de teste simples contendo apenas dois itens

        X-KDE-PluginInfo-Author=Alex Richardson
        X-KDE-PluginInfo-Email=foo.bar@email.org
        X-KDE-PluginInfo-Name=estruturasimples
        X-KDE-PluginInfo-Version=1.0
        X-KDE-PluginInfo-Website=https://www.plugin.org/
        X-KDE-PluginInfo-Category=structure
        X-KDE-PluginInfo-License=LGPL
        X-KDE-PluginInfo-EnabledByDefault=false
        

Estes campos devem parecer bem auto-explicativos, exceto pelo X-KDE-PluginInfo-Name. O valor deste campo deve corresponder ao nome da pasta que contém o arquivo bem como o nome do arquivo .desktop. Ao cria as definições de estrutura em XML o nome do arquivo .osd deve também corresponder ao nome.

Neste exemplo, teríamos uma pasta chamada estruturasimples que contém os arquivos estruturasimples.desktop. Ao definir as estruturas em XML, a pasta iria conter também um arquivo chamado estruturasimples.osd. Se usarmos o JavaScript, iríamos ter um arquivo chamado main.js em alternativa.

Para começar, vamos criar uma definição para uma estrutura de testes muito simples, contendo apenas tipos de dados primitivos (um caractere, um inteiro de 32 bits com sinal e um campo de bits). Isto poderia ser uma expresso em C/C++ como:

          struct simple {
            char aChar;
            int anInt;
            bool bitFlag :1;
            unsigned padding :7;
          };
          

O primeiro passo é escrever o arquivo .osd de acordo com o formato de arquivo definido na seção anterior. Nós o chamaremos de estruturasimples.osd:

          <?xml version="1.0" encoding="UTF-8"?>
          <data>
            <struct name="simple">
              <primitive name="aChar" type="Char"/>
              <primitive name="anInt" type="Int32"/>
              <bitfield name="bitFlag" type="bool" width="1"/>
              <bitfield name="padding" type="unsigned" width="7"/>
            </struct>
          </data>
          

que é bastante similar a uma definição em C/C++.

Agora crie uma pasta estruturasimples dentro da pasta de instalação da estrutura (veja como instalar manualmente definições de estruturas) e copie os dois arquivos para esta pasta. Agora você pode reiniciar o Okteta, para poder usar a nova estrutura.

Para implementar a estrutura acima em JavaScript, crie um arquivo chamado main.js em vez de estruturasimples.osd e altere o 'X-KDE-PluginInfo-Category=structure' para 'X-KDE-PluginInfo-Category=structure/js'. O conteúdo desse arquivo deverá ser:

        function init() {
          var estrutura = struct({
            caracter : char(),
            inteiro : int32(),
            opcaoBit : bitfield("bool", 1),
            preenchimento : bitfield("unsigned", 7),
          })
          return estrutura;
        }
        

A estrutura apresentada pelo Okteta é sempre o valor devolvido pela função init.

As seguintes funções poderão ser invocadas para criar um tipo primitivo:

A função 'bitfield' recebe dois parâmetros, sendo o primeiro um texto que consiste em bool, signed ou unsigned. O segundo parâmetro é um inteiro que define o tamanho em 'bits'.

A seguir, iremos criar uma estrutura mais complexa, que irá se chamar "complexa" e salvá-la num arquivo complexa.osd. Esta estrutura irá conter duas listas (uma de tamanho fixo e outra com o tamanho determinado durante a execução), assim como uma estrutura encadeada e uma união.

          <?xml version="1.0" encoding="UTF-8"?>
          <data>
            <struct name="complexa">
              <primitive name="tamanho" type="UInt8" />
              <union name="umaUniao">
                <array name="quatroBytes" length="4">
                  <primitive type="Int8" />
                </array>
              </union>
              <struct name="encadeado">
                <array name="texto" length="tamanho"> <!-- referencia o campo 'tamanho' acima -->
                  <primitive type="Char" />
                </array>
              </struct>
            </struct>
          </data>
          

Isto irá corresponder ao seguinte, em pseudo-C/C++

struct complexa {
            uint8_t tamanho;
            union umaUniao {
              int8_t quatroBytes[4];
            };
            struct encadeado {
              char texto[tamanho] //C++ não válido por referenciar o valor de 'tamanho'
            };
          };
          

A seguir, será criado o arquivo complexo.desktop, como foi feito no exemplo anterior (certifique-se de que define o X-KDE-PluginInfo-Name corretamente) e faça o mesmo para instalar ambos os arquivos.

Alguns exemplos de definições de estruturas poderão ser encontrados no repositório Git. Isso inclui, por exemplo, o cabeçalho dos arquivos PNG e ELF. Um esquema em XML que descreve a estrutura do arquivo .osd pode ser encontrado aqui. Se precisar de mais informações, sinta-se à vontade em contactar-me através do e-mail (arichardson.kde gmail.com)