Documentação

Índice


0.1 - Usando a ferramenta SHAN para instalação automatica dos módulos.

O shan é uma forma automatizada de procurar e instalar módulos! os módulos instalados vão estar disponíveis normalmente em sua HOME. Mas isto é uma questão de configuração, se no arquivo localizado em /etc/shan/shan.conf você especificar outro diretório, o mesmo mudará o rumo!
Para isto acontecer edite a váriavel DIRECTORY_INSTALL_MODULES="" adicionando o local mais apropriado!

Exemplo

DIRECTORY_INSTALL_MODULES="/home/slackjeff"

Você pode baixar o shan atráves do notabug, para gerar utilize o script localizado na raiz do programa chamado MAKE.



0.1.1 - Esqueleto do SHAN

Os diretórios que o BSO trabalha são:
/etc/shan/
/usr/bin/shan
/home/??????/BESOURO-MODULES

/etc/shan
Arquivos de configuração do SHAN, incluindo o mais importante shan.conf e modulos.txt

/usr/bin/shan
Arquivo executável do shan está localizado neste diretório!

/home/??????/shan-modules
Quando você baixa um módulo vira para o diretório BESOURO-MODULES, você pode especificar um novo diretório em /etc/shan/shan.conf



0.2 - Baixando os módulos manualmente

Se você não quiser usar o BSO para gerenciar e instalar os módulos automaticamente, poderá fazer este processo manual! Para isto a primeira coisa que você deve fazer é ir até Modules e procurar qual módulo lhe interessa!
Feito o processo da procura baixe para sua máquina, através da ferramenta wget ou da própria ferramenta do notabug. Como exemplo vamos usar o módulo simple-color!

Wget
Como usuário comum execute o wget:

$ wget https://notabug.org/jeffersonrocha/BESOURO-modules/raw/master/MODULES/simple-colors.bso

Notabug
Você pode clicar em Raw e abrirá um nova página contendo somente o texto puro, copiei todo código CTRL + A e cole em seu editor favorito CTRL + V.
Lembre se de quando salvar, por o mesmo nome de módulo para futuros updates você não se perder!



1.0 - Como inserir módulos em seu programa.

Após você ter todos módulos que lhe agrade, você deve primeiramente copiar o(s) módulo(s) que você precisa para uma localização exata onde seu programa vai puxar as informações!
Se caso vocẽ for disponibilizar seu programa para terceiros, você deve também fornecer o(s) módulo(s) junto. Vamos fazer um exemplo? vamos supor que eu baixei o módulo simple-debug.bso que serve para debuggar o programa, o primeiro passo que devo fazer é fazer uma copia para a raiz do meu programa, na sequência vou criar um diretório específico onde ficaram somente os módulos... Vamos lá.

Primeiramente vou criar um diretório para meus módulos, lembrando que estou no diretório raiz do meu programa.

$ mkdir modulos

Meu módulo está no diretório Downloads dentro do meu HOME.
$ cp Downloads/simple-debug.bso /home/slackjeff/Desktop/Scripts/Meu-Programa/modulos

$ ls modulos/
simple-debug.bso

Ótimo, agora vamos carregar o módulo dentro do programa chamado exemplo.sh, lembre-se de nada adianta ter o módulo e não carregar! É de extrema importância você programador fazer o carregamento do(s) módulo(s) no início do programa, logo após o cabeçalho... Para deixar bem organizado crie uma área somente para os módulos!
Para carregar o(s) módulo(s) vamos usar o comando . ou source, lembre-se que o . é mais portável, por isso é preferido!

Exemplo:

#!/bin/bash
#
#Autor: Jefferson Rocha
#Programa: Exemplo.sh
#Descrição: Um exemplo para o site do Besouro.

#CARREGAMENTO DE MÓDULOS
. modulos/simple-debug.bso

# Inicio programa
for x in 1 2 3 4 5 6 7 8 9 10; do
      echo "$x"
done

Lembre-se, se seu programa ficar em diretórios diferentes, por exemplo o executável do programa em /usr/bin/exemplo.sh e os módulos em /var/lib/exemplo/ você deve especificar também na chamada do módulo, se não é falha na certa, Exemplo:

#!/bin/bash
#
#Autor: Jefferson Rocha
#Programa: Exemplo.sh
#Descrição: Um exemplo para o site do Besouro.

#CARREGAMENTO DE MÓDULOS
. /usr/lib/EXEMPLO.sh/modulos/simple-debug.bso

# Inicio programa
for x in 1 2 3 4 5 6 7 8 9 10; do
      echo "$x"
done

Agora nosso módulo apesar de estar externamente na chamada do programa ficará uma coisa só, ou seja nada de subprocesso! É essencial você analisar a documentação do módulo para saber como é feito a chamada! se for uma função você necessita chamar a função se tiver váriaveis você precisa chamar a variável para funcionar! Em nosso exemplo o módulo simple-debug tem em seu conteúdo principal 2 funções...
Uma para ativar o debug e outra para desativar, para exemplo vamos debugar apenas a parte do loop for, que é o que nos interessa. Vamos ao exemplo:

#!/bin/bash
#
#Autor: Jefferson Rocha
#Programa: Exemplo.sh
#Descrição: Um exemplo para o site do Besouro.

#CARREGAMENTO DE MÓDULOS
. modulos/simple-debug.bso

printf '%b' "AQUI NÃO ESTÁ DEBUGANDO!!!"

debug_on
# Inicio programa
for x in 1 2 3 4 5 6 7 8 9 10; do
      echo "$x"
done
debug_off


printf '%b' "E nem aqui!!!"



2.0 - Criando seus próprios Módulos.

Para disponibilizar um módulo no repositório do BESOURO é necessário seguir boas práticas, ter portabilidade entre os shells BASH, KSH, ZSH e seguir um template que oferecemos.
Veja o que é necessário para o módulo ser aceito:

Seguindo a listagem acima e se seu módulo for importante, estará incluso!



2.1 Portabilidade dos módulos entre os Shells bash/ksh/zsh

Não adianta ter o melhor algoritmo, o módulo ser extremamente rápido e com poucos subprocessos/shell-filhos se não é portável! Para isto seguimos um padrão de portábilidade para Bash, Korn Shell, Zsh... Estes shells são extremamentes populares no mundo *Nix por isso é importante você como programador e mantenedor de um módulo ter instalados em seu sistema.
Vamos ver algumas substituições que você deverá fazer para seu módulo ficar totalmente portável!


Váriaveis locais em funções

Normalmente usamos local variavel="uma variavel aqui", o que acontece é que no Korn Shell não existe o local, substitua por typeset, e declare no inicio da função. Exemplo:

caminhos(){
# Declarações de váriaveis locais
typeset diretorio_origem
typeset diretorio_destino
       diretorio_origem="/home/fulano/"
       diretorio_destino="/mnt/backup"
}

logs(){
# Declarações de váriaveis locais
typeset log
typeset log_error
       log="/etc/log.example"
       log_error="/etc/logerror.example"
}


Váriaveis Somente Leitura/Constantes

Normalmente usamos declare com a opção -r, como falano no sub-tópico acima o declare não é portável! prefira o comando readonly para declarar variáveis somente leitura/constantes.

Não Portável

declare -r RUA="Pedrina barbosa"

# OU

declare -r RUA
RUA="Pedrina barbosa"

Portável

readonly RUA="Elis Regina"

# OU

readonly RUA
RUA="Elis Regina"


Funções

As funções não devem ser declaradas com o function na frente! este é um padrão bash.
Por isso NÃO USE! prefira apenas o nome da funcao e a chamada! funcao(){ printf '%b' "olá!?\n" ;}

FUNCAO_TOTAL(){
      printf '%b' "Agora sim!\n"
}


Impressão

Por muitas vezes usamos o comando echo não é? estamos habituados com ele, é simples e prático, pórem ele não é portável, ou melhor as opções/parâmetros dele não são!
Isto se dá ao fato de cada distribuição compilar ele de uma forma.
Prefira o comando printf, ele é 70% mais portável que o comando echo... Porém ele é mais lento, use com cautela, ele está presente no bash internamente/builtin mas em versões mais antigas não.
Novamente tenha cautela pois ele é mais pesado, use com moderação, se precisar quebrar linhas prefira o echo sem parâmetros.


Lower/Upper

Normalmente quando precisamos converter o conteúdo de uma váriavel usamos as expansões de váriaveis correto?

nome="jefferson"
nome=${nome^^} # Tudo em Maiúscula

nome="Andreia"
nome=${nome,,} # Tudo em Minúscula

Estas duas expansões não existem no zsh e no Ksh, prefira usar o tr ou até mesmo o sed para fazer estas substituição de valores.


Test

O alias do comando test que serve para testar expressões, colchetes duplos [[ EXPRESSÃO ]], não é portável! Se gosta de usar o colchetes ao invés do comando test em si, utilize apenas com um colchetes [ EXPRESSÃO ].

Não portável

[[ "$valor" -ne "3" ]]

Portável

[ "$valor" -ne "3" ]

# ou

test "$valor" -ne "3"


Verificação de dependências

Normalmente para verificar se existe uma ou mais dependência(s) no PATH usamos o comando which, ele além de ser mais pesado não é portável! o reserva seria o comando type, que é um utilitário presente em praticamente todos os *Nix, isso por ser um utilitário POSIX. Porém também precisamos tomar cuidados em seus parâmetros que mudam de um shell para outro. Por exemplo se usarmos a opção -P no bash, ele faz o mesmo trabalho que o which, porém não é portável e falha no ksh! Prefira a opção -p que é mais portável entre o bash, ksh e zsh! E para atingir praticamente muito mais shells você pode usar sem nenhuma opção e somente conferir o status de saída! 0 -> Tudo ocorreu bem 1 ou diferente de 0 -> O comando/programa não existe!

Não portável

$ which dialog
/usr/bin/dialog

# ou

$ type -P dialog
/usr/bin/dialog

Mais Portável

$ type dialog
dialog is /usr/bin/dialog

$ echo $?
0

$ type firefox
type: firefox: not found

$ echo $?
1

Feito isto somente redirecionamos a saída padrão STDOUT e a saída de erros STDER para o NULL e já temos um conferência mais portável!

2.2 Padrões de conferência.

Os módulos precisam ser bem testados, se caso algo falhe ou um conferência dá errado necessitamos enviar uma mensagem padronizada. No exemplo abaixo vamos supor que o utilitário tput não está instalado no sistema:

MODULE="Color Library"   # Nome do módulo
DEPENDS=("tput")             # Dependências

for dep in "${DEPENDS[@]}"; do
   if ! type "$dep" 1>/dev/null 2>&1; then
       printf '%b' "BESOURO Módulo Falhou! \n"
       printf '%b' "MÓDULO>> ${MODULE}\n"
       printf '%b' "${dep} NÃO ESTÁ INSTALADO! ABORTANDO\n"
       exit 1
   fi
done

BESOURO Módulo Falhou!
MÓDULO>> ${MODULE}
${dep} NÃO ESTÁ INSTALADO! ABORTANDO
exit 1

Use sempre este padrão!