Difference between revisions of "NML:Getting started"

From GRFSpecs
Jump to navigationJump to search
 
(22 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
{{NMLNavNoSubpages}}
  
{{NMLNavNoSubpages}}
   
  +
== What is NML? ==
−
NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files. Windows users can install the [http://bundles.openttdcoop.org/nml/nightlies/LATEST/ windows binary] which contains a binary which bundles all required libraries. Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:
  
  +
NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files.
  +
  +
== Installation ==
  +
=== pip ===
  +
If you are familiar with python and pip then you can just use
  +
pip-3.2 install nml
  +
This will install the required dependencies. Note that you may need administrator privileges for this to work.
  +
  +
=== Windows ===
  +
Windows users can install the [https://github.com/OpenTTD/nml/tags/ windows binary] which contains a binary which bundles (most) required libraries.
  +
  +
If execution fails due to missing MSVCR libraries or due to an invalid application configuration or similar error, you need to install [http://www.microsoft.com/en-gb/download/details.aspx?id=5555 this package from Microsoft].
  +
  +
  ⚫
If you go for a python install and the packages themselves (e.g. mingw or msys) instead of the pre-compiled binary: Apparently you can prevent a lot of problems by installing the 32bit version of python, even if you have a 64bit windows installation. Installing PIL might be troublesome if you do install the 64bit version of python.
  +
  +
=== Linux ===
  +
Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:
   
 
* '''python'''
  
* '''python'''
  +
** python 3.2 or newer (for nightly builds or NML 0.4.0 or newer, earlier versions require python 2.6 or 2.7)
−
** any version from 2.5 through 2.7 will do, but not 3.x
  
 
** downloadable from from http://www.python.org/)
  
** downloadable from from http://www.python.org/)
⚫
** Advise for windows users: apparently you can prevent a lot of problems by installing the 32bit version of python, even if you have a 64bit windows installation. Installing PIL might be troublesome if you do install the 64bit version of python.
  
 
* '''python image library'''
  
* '''python image library'''
−
** downloadable from http://www.pythonware.com/products/pil/
 +
** downloadable from https://pypi.python.org/pypi/Pillow/
 
* '''ply'''
  
* '''ply'''
 
** downloadable from http://www.dabeaz.com/ply/
  
** downloadable from http://www.dabeaz.com/ply/
 
* '''NML itself'''
  
* '''NML itself'''
−
** the latest (nightly) build can be downloaded from http://bundles.openttdcoop.org/nml/nightlies/LATEST/
 +
** the latest (nightly) build can be downloaded from https://github.com/OpenTTD/nml/tags
   
 
If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using <code style="color:darkgreen">python setup.py install</code> from your command prompt.
  
If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using <code style="color:darkgreen">python setup.py install</code> from your command prompt.
   
  +
For debian or ubunutu you might try to use pip for PIL/pillow when it is not in the package manager for python3:
−
OS X users: do not use PIL and PLY from Macports. They may not work properly. Install from downloads using the links above. Follow the instructions in the PIL readme carefully, it is prone to failing if you don't. You'll need GCC to build PIL, it's part of Apple developer tools on your OS X install DVD.
  
  +
sudo apt-get install python3
  +
sudo apt-get install python3-ply
  +
sudo apt-get install python3-pip
  +
sudo /usr/bin/pip-3.2 install pillow
   
  +
=== macOS ===
  +
macOS users have two choices: install the dependencies manually as described in the Linux section above, for use with the python version that ships with macOS. Or install everything from brew or macports, including a new python version (using brew or macports eases upgrading). Using a python virtualenv for nml is optional, but recommended.
  +
  +
=== Installing manually (any system) ===
  +
We assume that you have a python setup (2.6 ... 2.7) where the distutils are available so that setup.py can be executed. You'll additionally need a gcc compiler in your path. On linux it is strongly recommended to use your package manager to install these packages.
  +
  +
==== Install PLY ====
  +
This is easy. Get the library from the link as mentioned above.
  +
Install it from the unpacked PLY directory via
  +
sudo python setup.py install
  +
  +
==== Install the Python Imaging Library (PIL) ====
  +
Get the library from the above mentioned link (the source kit for PIL 1.1.7). From the PIL source directory, test the setup for all available dependencies:
  +
python setup.py build_ext -i
  +
You should get an output like which concludes with a summary of the available dependencies:
  +
PIL 1.1.7 SETUP SUMMARY
  +
--------------------------------------------------------------------
  +
--- TKINTER support available
  +
--- JPEG support available
  +
--- ZLIB (PNG/ZIP) support available
  +
--- FREETYPE2 support available
  +
--- LITTLECMS support available
  +
--------------------------------------------------------------------
  +
If you're missing zlib or jpeg support, install those libraries, too.
  +
  +
If that build shows everything available, test the setup:
  +
python selftest.py
  +
A successful selftest will result in
  +
--------------------------------------------------------------------
  +
PIL 1.1.7 TEST SUMMARY
  +
--------------------------------------------------------------------
  +
Python modules loaded from ./PIL
  +
Binary modules loaded from ./PIL
  +
--------------------------------------------------------------------
  +
--- PIL CORE support ok
  +
--- TKINTER support ok
  +
--- JPEG support ok
  +
--- ZLIB (PNG/ZIP) support ok
  +
--- FREETYPE2 support ok
  +
--- LITTLECMS support ok
  +
--------------------------------------------------------------------
  +
Running selftest:
  +
--- 57 tests passed.
  +
If all is successful, finally install the library:
  +
sudo python setup.py install
  +
  +
==== Install NML ====
  +
Now, that you have installed ply and pil, then you can install NML from the unpacked nml directory:
  +
sudo python setup.py install
  +
  +
== Testing the installation ==
 
To verify that everything is installed, enter <code style="color:darkgreen">nmlc --version</code> in your command line. This should output the version of NML as well as the version of the installed libraries.
  
To verify that everything is installed, enter <code style="color:darkgreen">nmlc --version</code> in your command line. This should output the version of NML as well as the version of the installed libraries.
   
Line 32: Line 104:
 
The full syntax is:
  
The full syntax is:
   
−
Usage: nmlc [options] &lt;filename&gt;
 +
Usage: nmlc [options] <filename>
−
Where &lt;filename&gt; is the nml file to parse
 +
Where <filename> is the nml file to parse
 
 
−
Options:
 +
Options:
 
--version show program's version number and exit
  
--version show program's version number and exit
 
-h, --help show this help message and exit
  
-h, --help show this help message and exit
 
-d, --debug write the AST to stdout
  
-d, --debug write the AST to stdout
 
-s, --stack Dump stack when an error occurs
  
-s, --stack Dump stack when an error occurs
−
--grf=&lt;file&gt; write the resulting grf to &lt;file&gt;
 +
--grf=<file> write the resulting grf to <file>
−
--nfo=&lt;file&gt; write nfo output to &lt;file&gt;
 +
--md5=<file> Write an md5sum of the resulting grf to <file>
  +
--nfo=<file> write nfo output to <file>
 
-M output a rule suitable for make describing the
  
-M output a rule suitable for make describing the
 
graphics dependencies of the main grf file (requires
  
graphics dependencies of the main grf file (requires
 
input file or --grf)
  
input file or --grf)
−
--MF=&lt;file&gt; When used with -M, specifies a file to write the
 +
--MF=<file> When used with -M, specifies a file to write the
 
dependencies to
  
dependencies to
−
--MT=&lt;file&gt; target of the rule emitted by dependency generation
 +
--MT=<file> target of the rule emitted by dependency generation
 
(requires -M)
  
(requires -M)
 
-c crop extraneous transparent blue from real sprites
  
-c crop extraneous transparent blue from real sprites
 
-u save uncompressed data in the grf file
  
-u save uncompressed data in the grf file
−
--nml=&lt;file&gt; write optimized nml to &lt;file&gt;
 +
--nml=<file> write optimized nml to <file>
−
-o &lt;file&gt;, --output=&lt;file&gt;
 +
-o <file>, --output=<file>
−
write output(nfo/grf) to &lt;file&gt;
 +
write output(nfo/grf) to <file>
−
-t &lt;file&gt;, --custom-tags=&lt;file&gt;
 +
-t <file>, --custom-tags=<file>
−
Load custom tags from &lt;file&gt; [default:
 +
Load custom tags from <file> [default:
 
custom_tags.txt]
  
custom_tags.txt]
−
-l &lt;dir&gt;, --lang-dir=&lt;dir&gt;
 +
-l <dir>, --lang-dir=<dir>
−
Load language files from directory &lt;dir&gt; [default:
 +
Load language files from directory <dir> [default:
 
lang]
  
lang]
  ⚫
--default-lang=<file>
−
-a &lt;dir&gt;, --sprites-dir=&lt;dir&gt;
  
−
Store 32bpp sprites in directory &lt;dir&gt; [default:
 +
The default language is stored in <file> [default:
⚫
sprites]
  
⚫
--default-lang=&lt;file&gt;
  
−
The default language is stored in &lt;file&gt; [default:
  
 
english.lng]
  
english.lng]
−
--start-sprite=&lt;num&gt; Set the first sprite number to write (do not use
 +
--start-sprite=<num> Set the first sprite number to write (do not use
 
except when you output nfo that you want to include in
  
except when you output nfo that you want to include in
 
other files)
  
other files)
−
-p &lt;palette&gt;, --palette=&lt;palette&gt;
 +
-p <palette>, --palette=<palette>
−
Force nml to use the palette &lt;pal&gt; [default: ANY].
 +
Force nml to use the palette <pal> [default: ANY].
−
Valid values are 'DOS', 'WIN', 'ANY'
 +
Valid values are 'DEFAULT', 'LEGACY', 'ANY'
  +
--quiet Disable all warnings. Errors will be printed normally.
  +
-n, --no-cache Disable caching of sprites in .cache[index] files,
  ⚫
which may reduce compilation time.
  +
  +
== Syntax highlighting ==
  +
For some editors a matching syntax highlighting file is generated for each build of NML:
  +
  +
* [http://bundles.openttdcoop.org/nml/push/LATEST/nml_notepadpp.xml Notepad++]
  +
* [http://bundles.openttdcoop.org/nml/push/LATEST/nml_kate.xml Kate]
  +
  +
For a few editors there exist syntax highlighting rules, made at a certain point, see the [http://dev.openttdcoop.org/projects/home/documents DevZone documents] for details. These files might be more or less outdated and not support the full syntax of NML:
  +
* [http://dev.openttdcoop.org/documents/26 Geany]
  +
Please make available to us any updates you might have made. If you want the highlighting files automatically generated for your editor, we'll happily accept patches. See [https://hg.openttdcoop.org/nml/files/tip/nml/editors here] for the existing generation scripts.

Latest revision as of 10:44, 25 February 2022

What is NML?

NML is a a python-based compiler, capable to compile NML files (along with their associated language, sound and graphic files) into grf and / or nfo files.

Installation

pip

If you are familiar with python and pip then you can just use 

   pip-3.2 install nml

This will install the required dependencies. Note that you may need administrator privileges for this to work.

Windows

Windows users can install the windows binary which contains a binary which bundles (most) required libraries.

If execution fails due to missing MSVCR libraries or due to an invalid application configuration or similar error, you need to install this package from Microsoft.


If you go for a python install and the packages themselves (e.g. mingw or msys) instead of the pre-compiled binary: Apparently you can prevent a lot of problems by installing the 32bit version of python, even if you have a 64bit windows installation. Installing PIL might be troublesome if you do install the 64bit version of python.

Linux

Users on other OS need to install them separately, best by means of their packet manager. In order to work, the following items are required:

If you don't install these with the packet manager of your choice (or there is none like on windows and you don't use the pre-compiled binary file), you should install these libraries as well as NML itself using python setup.py install from your command prompt.

For debian or ubunutu you might try to use pip for PIL/pillow when it is not in the package manager for python3: 

sudo apt-get install python3
sudo apt-get install python3-ply
sudo apt-get install python3-pip
sudo /usr/bin/pip-3.2 install pillow

macOS

macOS users have two choices: install the dependencies manually as described in the Linux section above, for use with the python version that ships with macOS. Or install everything from brew or macports, including a new python version (using brew or macports eases upgrading). Using a python virtualenv for nml is optional, but recommended.

Installing manually (any system)

We assume that you have a python setup (2.6 ... 2.7) where the distutils are available so that setup.py can be executed. You'll additionally need a gcc compiler in your path. On linux it is strongly recommended to use your package manager to install these packages.

Install PLY

This is easy. Get the library from the link as mentioned above. Install it from the unpacked PLY directory via 

sudo python setup.py install

Install the Python Imaging Library (PIL)

Get the library from the above mentioned link (the source kit for PIL 1.1.7). From the PIL source directory, test the setup for all available dependencies: 

python setup.py build_ext -i

You should get an output like which concludes with a summary of the available dependencies: 

PIL 1.1.7 SETUP SUMMARY
--------------------------------------------------------------------
--- TKINTER support available
--- JPEG support available
--- ZLIB (PNG/ZIP) support available
--- FREETYPE2 support available
--- LITTLECMS support available
--------------------------------------------------------------------

If you're missing zlib or jpeg support, install those libraries, too.

If that build shows everything available, test the setup: 

python selftest.py

A successful selftest will result in 

--------------------------------------------------------------------
PIL 1.1.7 TEST SUMMARY 
--------------------------------------------------------------------
Python modules loaded from ./PIL
Binary modules loaded from ./PIL
--------------------------------------------------------------------
--- PIL CORE support ok
--- TKINTER support ok
--- JPEG support ok
--- ZLIB (PNG/ZIP) support ok
--- FREETYPE2 support ok
--- LITTLECMS support ok
--------------------------------------------------------------------
Running selftest:
--- 57 tests passed.

If all is successful, finally install the library: 

sudo python setup.py install

Install NML

Now, that you have installed ply and pil, then you can install NML from the unpacked nml directory: 

sudo python setup.py install

Testing the installation

To verify that everything is installed, enter nmlc --version in your command line. This should output the version of NML as well as the version of the installed libraries.

Examples for small NML "projects" are found in the examples and regression folder of NML. Generally it's assumed that the language files are in a separate language folder lang, thus a simple project may look like this: 

mynewgrf.nml
graphics.png
funny_sound.wav

lang/english.lng

The compiler itself nmlc is a command line tool and can take a number of parameters, at least the nml filename which it shall process, e.g. nmlc mynewgrf.nml will compile your nml file into the grf-file mynewgrf.grf.

The full syntax is: 

Usage: nmlc [options] <filename>
Where <filename> is the nml file to parse

Options: 

 --version             show program's version number and exit
 -h, --help            show this help message and exit
 -d, --debug           write the AST to stdout
 -s, --stack           Dump stack when an error occurs
 --grf=<file>          write the resulting grf to <file>
 --md5=<file>          Write an md5sum of the resulting grf to <file>
 --nfo=<file>          write nfo output to <file>
 -M                    output a rule suitable for make describing the
                       graphics dependencies of the main grf file (requires
                       input file or --grf)
 --MF=<file>           When used with -M, specifies a file to write the
                       dependencies to
 --MT=<file>           target of the rule emitted by dependency generation
                       (requires -M)
 -c                    crop extraneous transparent blue from real sprites
 -u                    save uncompressed data in the grf file
 --nml=<file>          write optimized nml to <file>
 -o <file>, --output=<file>
                       write output(nfo/grf) to <file>
 -t <file>, --custom-tags=<file>
                       Load custom tags from <file> [default:
                       custom_tags.txt]
 -l <dir>, --lang-dir=<dir>
                       Load language files from directory <dir> [default:
                       lang]
 --default-lang=<file>
                       The default language is stored in <file> [default:
                       english.lng]
 --start-sprite=<num>  Set the first sprite number to write (do not use
                       except when you output nfo that you want to include in
                       other files)
 -p <palette>, --palette=<palette>
                       Force nml to use the palette <pal> [default: ANY].
                       Valid values are 'DEFAULT', 'LEGACY', 'ANY'
 --quiet               Disable all warnings. Errors will be printed normally.
 -n, --no-cache        Disable caching of sprites in .cache[index] files,
                       which may reduce compilation time.

Syntax highlighting

For some editors a matching syntax highlighting file is generated for each build of NML:

For a few editors there exist syntax highlighting rules, made at a certain point, see the DevZone documents for details. These files might be more or less outdated and not support the full syntax of NML:

Please make available to us any updates you might have made. If you want the highlighting files automatically generated for your editor, we'll happily accept patches. See here for the existing generation scripts.

Retrieved from ‘https://newgrf-specs.tt-wiki.net/index.php?title=NML:Getting_started&oldid=4172’