A Discrete-Event Network Simulator
Rastreamento

Iniciando

Baixando o ns-3

O ns-3, como um todo, é bastante complexo e possui várias dependências. Isto também é verdade para as ferramentas que fornecem suporte ao ns-3 (exemplos, “GNU toolchain”, Mercurial e um editor para a programação), desta forma é necessário assegurar que várias bibliotecas estejam presentes no sistema. O ns-3 fornece um Wiki com várias dicas sobre o sistema. Uma das páginas do Wiki é a página de instalação (“Installation”) que está disponível em: http://www.nsnam.org/wiki/Installation.

A seção de pré-requisitos (“Prerequisites”) do Wiki explica quais pacotes são necessários para a instalação básica do ns-3 e também fornece os comandos usados para a instalação nas variantes mais comuns do Linux. Os usuários do Cygwin devem utilizar o Cygwin installer.

Seria interessante explorar um pouco o Wiki, pois lá existe uma grande variedade de informações.

A partir deste ponto considera-se que o leitor está trabalhando com Linux ou em um ambiente que o emule (Linux, Cygwin, etc), que tenha o “GNU toolchain” instalado, bem como os pré-requisitos mencionados anteriormente. Também assume-se que o leitor tenha o Mercurial e o Waf instalados e funcionando em seu sistema.

Os códigos fonte do ns-3 estão disponíveis através dos repositórios do Mercurial no servidor http://code.nsnam.org. Os fontes compactados podem ser obtidos em http://www.nsnam.org/releases/. No final desta seção há instruções de como obter uma versão compactada. No entanto, a não ser que se tenha uma boa razão, recomenda-se o uso do Mercurial para acesso ao código.

A maneira mais simples de iniciar com o Mercurial é usando o ambiente ns-3-allinone. Trata-se de um conjunto de scripts que gerencia o baixar e o construir de vários sub-sistemas do ns-3. Recomenda-se que os pouco experientes iniciem sua aventura neste ambiente, pois irá realmente facilitar a jornada.

Obtendo o ns-3 usando o Mercurial

Para iniciar, uma boa prática é criar um diretório chamado repos no diretório home sobre o qual será mantido o repositório local do Mercurial. Dica: iremos assumir que o leitor fez isto no restante deste tutorial, então é bom executar este passo! Se o leitor adotar esta abordagem é possível obter a cópia do ns-3-allinone executando os comandos a seguir no shell Linux (assumindo que o Mercurial está instalado):

cd
mkdir repos
cd repos
hg clone http://code.nsnam.org/ns-3-allinone

Quando executarmos o comando hg (Mercurial), teremos como saída algo como:

destination directory: ns-3-allinone
requesting all changes
adding changesets
adding manifests
adding file changes
added 31 changesets with 45 changes to 7 files
7 files updated, 0 files merged, 0 files removed, 0 files unresolved

Depois que o comando clone for executado com sucesso, teremos um diretório chamado ns-3-allinone dentro do diretório ~/repos. O conteúdo deste diretório deve ser algo como:

build.py*  constants.py  dist.py*  download.py*  README  util.py

Até agora foram baixados alguns scripts em Python. O próximo passo será usar estes scripts para baixar e construir a distribuição ns-3 de sua escolha.

Acessando o endereço: http://code.nsnam.org/, observa-se vários repositórios. Alguns são privados à equipe de desenvolvimento do ns-3. Os repositórios de interesse ao leitor estarão prefixados com “ns-3”. As releases oficiais do ns-3 estarão enumeradas da seguinte forma: ns-3.<release>.<hotfix>. Por exemplo, uma segunda atualização de pequeno porte (hotfix) de uma hipotética release 42, seria enumerada da seguinte maneira: ns-3.42.2.

A versão em desenvolvimento (que ainda não é uma release oficial) pode ser encontrada em http://code.nsnam.org/ns-3-dev/. Os desenvolvedores tentam manter este repositório em um estado consistente, mas podem existir códigos instáveis. Recomenda-se o uso de uma release oficial, a não ser que se necessite das novas funcionalidades introduzidas.

Uma vez que o número das versões fica mudando constantemente, neste tutorial será utilizada a versão ns-3-dev, mas o leitor pode escolher outra (por exemplo, ns-3.10). A última versão pode ser encontrada inspecionando a lista de repositórios ou acessando a página “ns-3 Releases” e clicando em latest release.

Entre no diretório ns-3-allinone criado anteriormente. O arquivo download.py será usado para baixar as várias partes do ns-3 que serão utilizadas.

Execute os seguintes comandos no shell (lembre-se de substituir o número da versão no lugar de ns-3-dev pela que escolheu, por exemplo, se você optou por usar a décima release estável, então deve usar o nome "ns-3.10").

./download.py -n ns-3-dev

O ns-3-dev é o padrão quando usamos a opção -n, assim o comando poderia ser ./download.py -n. O exemplo redundante é apenas para ilustra como especificar repositórios alternativos. Um comando mais simples para obter o ns-3-dev seria:

./download.py

Com o comando hg (Mercurial) em execução devemos ver a seguinte saída:

    #
    # Get NS-3
    #

Cloning ns-3 branch
 =>  hg clone http://code.nsnam.org/ns-3-dev ns-3-dev
requesting all changes
adding changesets
adding manifests
adding file changes
added 4634 changesets with 16500 changes to 1762 files
870 files updated, 0 files merged, 0 files removed, 0 files unresolved

Esta é a saída do script de download obtendo o código atual do repositório ns-3.

O script de download reconhece que partes do ns-3 não são suportadas na plataforma. Dependendo do sistema, pode ser que a saída não seja exatamente como a mostrada a seguir. Porém, a maioria dos sistemas apresentarão algo como:

    #
    # Get PyBindGen
    #

Required pybindgen version:  0.10.0.640
Trying to fetch pybindgen; this will fail if no network connection is available.
Hit Ctrl-C to skip.
 =>  bzr checkout -rrevno:640 https://launchpad.net/pybindgen pybindgen
Fetch was successful.

Este é o script de download obtendo um gerador de bindings Python — um binding é literalmente a ligação ou ponte entre dois sistemas, chamaremos aqui de extensões Python. Também será necessário o Bazaar (brz) para baixar o PyBindGen. O Bazaar é um sistema de controle de versões. Em seguida, o leitor deve ver (com algumas variações devido as plataformas) algo parecido com as seguintes linhas:

    #
    # Get NSC
    #

Required NSC version:  nsc-0.5.0
Retrieving nsc from https://secure.wand.net.nz/mercurial/nsc
 =>  hg clone https://secure.wand.net.nz/mercurial/nsc nsc
requesting all changes
adding changesets
adding manifests
adding file changes
added 273 changesets with 17565 changes to 15175 files
10622 files updated, 0 files merged, 0 files removed, 0 files unresolved

Neste momento, o script de download baixa o Network Simulation Cradle - NSC. Note que o NSC não é suportado no OSX ou Cygwin e trabalha melhor com o gcc-3.4, gcc-4.2 ou superiores.

Depois que o script download.py tiver completado sua tarefa, veremos vários diretórios novos dentro de ~/repos/ns-3-allinone:

build.py*     constants.pyc  download.py*  nsc/        README      util.pyc
constants.py  dist.py*       ns-3-dev/     pybindgen/  util.py

Por fim, no diretório ns-3-dev que está dentro do diretório ~/repos/ns-3-allinone deve existir, depois dos passos anteriores, o seguinte conteúdo:

AUTHORS       doc       ns3            scratch   testpy.supp  VERSION   waf-tools
bindings      examples  README         src       utils        waf*      wscript
CHANGES.html  LICENSE   RELEASE_NOTES  test.py*  utils.py     waf.bat*  wutils.py

Agora está tudo pronto para a construção da distribuição do ns-3.

Obtendo o ns-3 compactado (Tarball)

O processo de download do ns-3 compactado é mais simples do que o processo usando o Mercurial, porque tudo que precisamos já vem empacotado. Basta escolher a versão, baixá-la e extraí-la.

Como mencionado anteriormente, uma boa prática é criar um diretório chamado repos no diretório home para manter a cópia local dos repositórios do Mercurial. Da mesma forma, pode-se manter também um diretório chamado tarballs para manter as versões obtidas via arquivo compactado. Dica: o tutorial irá assumir que o download foi feito dentro do diretório ``repos``. Se a opção for pelo método do arquivo compactado, pode-se obter a cópia de uma versão digitando os seguintes comandos no shell Linux (obviamente, substitua os números de versões do comando para o valor apropriado):

cd
mkdir tarballs
cd tarballs
wget http://www.nsnam.org/releases/ns-allinone-3.10.tar.bz2
tar xjf ns-allinone-3.10.tar.bz2

Dentro do diretório ns-allinone-3.10 extraído, deverá haver algo como:

build.py      ns-3.10/      pybindgen-0.15.0/    util.py
constants.py  nsc-0.5.2/    README

Agora está tudo pronto para a construção da distribuição do ns-3.

Construindo o ns-3

Construindo com o build.py

A primeira construção do ns-3 deve ser feita usando o ambiente allinone. Isto fará com que o projeto seja configurado da maneira mais funcional.

Entre no diretório criado na seção “Obtendo o ns-3”. Se o Mercurial foi utilizado, então haverá um diretório chamado ns-3-allinone localizado dentro de ~/repos. Se foi utilizado o arquivo compactado, haverá um diretório chamado ns-allinone-3.10 dentro do diretório ~/tarballs. Lembre-se de adequar os nomes conforme os arquivos obtidos e diretórios criados. Agora, digite o seguinte comando:

./build.py --enable-examples --enable-tests

Foram utilizadas as opções --enable-examples e --enable-tests pois o tutorial irá trabalhar com exemplos e testes, e, por padrão, eles não são construídos. Futuramente, o leitor poderá construir sem estas opções.

Serão exibidas muitas saídas típicas de um compilador conforme o código é construído. Finalmente, no final do processo, deverá aparecer uma saída como esta:

Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (2m30.586s)

Modules built:
aodv                      applications              bridge
click                     config-store              core
csma                      csma-layout               dsdv
emu                       energy                    flow-monitor
internet                  lte                       mesh
mobility                  mpi                       netanim
network                   nix-vector-routing        ns3tcp
ns3wifi                   olsr                      openflow
point-to-point            point-to-point-layout     propagation
spectrum                  stats                     tap-bridge
template                  test                      tools
topology-read             uan                       virtual-net-device
visualizer                wifi                      wimax

Uma vez que o projeto foi construído, pode-se deixar de lado os scripts ns-3-allinone. O leitor já obteve o que precisava e agora irá interagir diretamente com o Waf no diretório ns-3-dev. Mude para o diretório ns-3-dev (ou para o diretório apropriado de sua versão).

cd ns-3-dev

Construindo com o Waf

O Waf é utilizado para configurar e construir o projeto do ns-3. Não é estritamente necessário neste ponto, mas será valioso quando se forem necessárias alterações nas configurações do projeto. Provavelmente a mudança mais útil que será feita futuramente é a construção de uma versão do código otimizado. Por padrão, o projeto é construído com a opção de depuração (debug), para verificação de erros. Então, para construir um projeto otimizado, deve-se executar o seguinte comando (ainda com suporte a testes e exemplos):

./waf -d optimized --enable-examples --enable-tests configure

Isto executa o Waf fora do diretório local (o que é bem conveniente). Como o sistema em construção verifica várias dependências, deverá aparecer uma saída similar com a que segue:

Checking for program g++                 : ok /usr/bin/g++
Checking for program cpp                 : ok /usr/bin/cpp
Checking for program ar                  : ok /usr/bin/ar
Checking for program ranlib              : ok /usr/bin/ranlib
Checking for g++                         : ok
Checking for program pkg-config          : ok /usr/bin/pkg-config
Checking for -Wno-error=deprecated-declarations support : yes
Checking for -Wl,--soname=foo support                   : yes
Checking for header stdlib.h                            : ok
Checking for header signal.h                            : ok
Checking for header pthread.h                           : ok
Checking for high precision time implementation         : 128-bit integer
Checking for header stdint.h                            : ok
Checking for header inttypes.h                          : ok
Checking for header sys/inttypes.h                      : not found
Checking for library rt                                 : ok
Checking for header netpacket/packet.h                  : ok
Checking for pkg-config flags for GSL                   : ok
Checking for header linux/if_tun.h                      : ok
Checking for pkg-config flags for GTK_CONFIG_STORE      : ok
Checking for pkg-config flags for LIBXML2               : ok
Checking for library sqlite3                            : ok
Checking for NSC location                               : ok ../nsc (guessed)
Checking for library dl                                 : ok
Checking for NSC supported architecture x86_64          : ok
Checking for program python                             : ok /usr/bin/python
Checking for Python version >= 2.3                      : ok 2.5.2
Checking for library python2.5                          : ok
Checking for program python2.5-config                   : ok /usr/bin/python2.5-config
Checking for header Python.h                            : ok
Checking for -fvisibility=hidden support                : yes
Checking for pybindgen location                         : ok ../pybindgen (guessed)
Checking for Python module pybindgen                    : ok
Checking for pybindgen version                          : ok 0.10.0.640
Checking for Python module pygccxml                     : ok
Checking for pygccxml version                           : ok 0.9.5
Checking for program gccxml                             : ok /usr/local/bin/gccxml
Checking for gccxml version                             : ok 0.9.0
Checking for program sudo                               : ok /usr/bin/sudo
Checking for program hg                                 : ok /usr/bin/hg
Checking for program valgrind                           : ok /usr/bin/valgrind
---- Summary of optional NS-3 features:
Threading Primitives          : enabled
Real Time Simulator           : enabled
Emulated Net Device           : enabled
GNU Scientific Library (GSL)  : enabled
Tap Bridge                    : enabled
GtkConfigStore                : enabled
XmlIo                         : enabled
SQlite stats data output      : enabled
Network Simulation Cradle     : enabled
Python Bindings               : enabled
Python API Scanning Support   : enabled
Use sudo to set suid bit      : not enabled (option --enable-sudo not selected)
Build tests                   : enabled
Build examples                : enabled
Static build                  : not enabled (option --enable-static not selected)
'configure' finished successfully (2.870s)

Repare a última parte da saída. Algumas opções do ns-3 não estão habilitadas por padrão ou necessitam de algum suporte do sistema para funcionar corretamente. Por exemplo, para habilitar XmlTo, a biblioteca libxml-2.0 deve estar presente no sistema. Se a biblioteca não estiver instalada esta funcionalidade não é habilitada no ns-3 e uma mensagem é apresentada. Note também que existe uma funcionalidade que utiliza o Sudo para configurar o suid de certos programas. Isto não está habilitado por padrão, então esta funcionalidade é reportada como não habilitada (not enabled).

Vamos configurar uma construção do ns-3 com suporte a depuração, bem como, vamos incluir exemplos e testes. Para isto devemos executar:

./waf -d debug --enable-examples --enable-tests configure

Pronto o sistema está configurado, agora podemos construir nossa versão digitando:

./waf

Alguns comandos do Waf são válidos apenas na fase de construção e outros são válidos na fase de configuração do sistema. Por exemplo, se o leitor espera usar características de emulação do ns-3, deve habilitar o suid usando o Sudo como descrito anteriormente, isto na fase de configuração. O comando utilizado, incluindo exemplos e testes, será:

./waf -d debug --enable-sudo --enable-examples --enable-tests configure

Com esta configuração, o Waf executará o Sudo para alterar programas que criam soquetes para executar o código de emulação como root. Existem várias outras opções de configuração e construção disponíveis no Waf. Para explorar estas opções, digite:

./waf --help

Alguns comandos de teste serão utilizados na próxima seção.

Como pôde ser notado, a construção do ns-3 foi feita duas vezes. Isto para que o leitor saiba como trocar a configuração para construir código otimizado no futuro.

Testando o ns-3

Para executar os testes de unidade do ns-3, basta chamar o arquivo ./test.py da seguinte forma:

./test.py -c core

Estes testes são executados em paralelo pelo Waf. No final, uma mensagem como a que segue deve aparecer.

47 of 47 tests passed (47 passed, 0 failed, 0 crashed, 0 valgrind errors)

Esta é uma mensagem importante.

Também haverá saídas da execução do teste e estas geralmente são algo como:

Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
'build' finished successfully (1.799s)

Modules built:
aodv                      applications              bridge
click                     config-store              core
csma                      csma-layout               dsdv
emu                       energy                    flow-monitor
internet                  lte                       mesh
mobility                  mpi                       netanim
network                   nix-vector-routing        ns3tcp
ns3wifi                   olsr                      openflow
point-to-point            point-to-point-layout     propagation
spectrum                  stats                     tap-bridge
template                  test                      tools
topology-read             uan                       virtual-net-device
visualizer                wifi                      wimax

PASS: TestSuite ns3-wifi-interference
PASS: TestSuite histogram
PASS: TestSuite sample
PASS: TestSuite ipv4-address-helper
PASS: TestSuite devices-wifi
PASS: TestSuite propagation-loss-model

...

PASS: TestSuite attributes
PASS: TestSuite config
PASS: TestSuite global-value
PASS: TestSuite command-line
PASS: TestSuite basic-random-number
PASS: TestSuite object
PASS: TestSuite random-number-generators
95 of 95 tests passed (95 passed, 0 failed, 0 crashed, 0 valgrind errors)

Este comando é normalmente executado pelos usuários para verificar se o ns-3 foi construído corretamente.

Executando um código (Script)

Os códigos normalmente são executados sob o controle do Waf. Isto assegura que os caminhos das bibliotecas compartilhadas estejam corretas e que estarão disponíveis em tempo de execução. Para executar um programa, basta usar a opção --run no Waf. Para executar um equivalente ao “Olá mundo” (Hello world) no ns-3, utilizamos o comando:

./waf --run hello-simulator

O Waf primeiro verifica se o programa foi construído corretamente e se necessário, o constrói. Então executa o programa, que fornece a seguinte saída:

Hello Simulator

Parabéns. Você agora é um usuário ns-3

O que fazer se o comando não gerar uma saída?

Se a mensagem Hello Simulator não aparece, mas o Waf gera saídas indicando que a construção do sistema foi executada com sucesso, é possível que o leitor tenha trocado o sistema para o modo otimizado na seção Construindo com o Waf, e tenha esquecido de voltar ao modo de depuração. Todas as saídas utilizadas neste tutorial são feitas com um componente especial de registro (logging) do ns-3 que é muito útil para mostrar mensagens na tela. As saídas deste componente são automaticamente desabilitadas quando o código é contruído na forma otimizada. Para produzir as saídas, digite o seguinte comando,

./waf -d debug --enable-examples --enable-tests configure

para dizer ao Waf para construir o ns-3 com a versão de depuração e incluir exemplos e testes. Ainda é necessário digitar o seguinte comando para a construção:

./waf

Agora, ao executar o programa hello-simulator devemos ter a seguinte a saída.

Se o leitor for executar seus programas sob outras ferramentas, tais como Gdb ou Valgrind, é recomendável que leia a seguinte entrada no Wiki.

Tabela de Conteúdo

Tópico anterior

Recursos

Próximo tópico

Visão Conceitual

Esta Página